LiveKit.Error exception (LiveKit v0.1.0)

The single error type returned by every public LiveKit SDK function.

LiveKit.Error is both an exception (so bang functions can raise it) and a plain struct that is returned inside {:error, error} tuples by the non-bang API.

iex> {:error, error} = LiveKit.Config.new(url: "https://example.livekit.cloud")
iex> error.type
:configuration

Redaction

Errors are frequently logged or inspected by callers, so this module goes out of its way to never carry credentials:

meta values are sanitized with sanitize/1, which drops well-known credential keys and replaces JWT-shaped strings with "[REDACTED]".
The derived Inspect implementation is the default struct one, but since no field ever holds a secret, inspecting an error is safe.

Anything placed into meta by the SDK passes through sanitize/1 first.

Summary

Types

error_type()

Classification of a failure.

t()

Functions

authentication(message, opts \\ [])

Builds an :authentication error.

configuration(message, opts \\ [])

Builds a :configuration error.

decoding(message, opts \\ [])

Builds a :decoding error.

encoding(message, opts \\ [])

Builds an :encoding error.

http(message, opts \\ [])

Builds an :http error for a non-success response without a Twirp payload.

new(opts)

Builds an error.

sanitize(struct)

Removes credentials from an arbitrary metadata map.

timeout(message, opts \\ [])

Builds a :timeout error. Timeouts are retryable by default.

transport(message, opts \\ [])

Builds a :transport error. Transport failures are retryable by default.

twirp(message, opts \\ [])

Builds a :twirp error from a decoded Twirp JSON error body.

validation(message, opts \\ [])

Builds a :validation error.

Types

error_type()

@type error_type() ::
  :configuration
  | :validation
  | :authentication
  | :transport
  | :timeout
  | :http
  | :twirp
  | :encoding
  | :decoding
  | :protobuf
  | :unknown

Classification of a failure.

:configuration - invalid client/config construction options
:validation - invalid arguments to an otherwise well-formed call
:authentication - the service token could not be built or was rejected
:transport - the request never produced an HTTP response
:timeout - connect or receive timeout
:http - non-success HTTP response that is not a Twirp error
:twirp - structured Twirp JSON error payload
:encoding - request could not be encoded
:decoding - response body could not be decoded
:protobuf - protobuf specific encode/decode failure
:unknown - anything that could not be classified

t()

@type t() :: %LiveKit.Error{
  __exception__: true,
  code: String.t() | nil,
  message: String.t(),
  meta: map(),
  retryable: boolean(),
  status: pos_integer() | nil,
  type: error_type()
}

Functions

authentication(message, opts \\ [])

@spec authentication(
  String.t(),
  keyword()
) :: t()

Builds an :authentication error.

Examples

iex> LiveKit.Error.authentication("no grant requested").type
:authentication

configuration(message, opts \\ [])

@spec configuration(
  String.t(),
  keyword()
) :: t()

Builds a :configuration error.

Examples

iex> LiveKit.Error.configuration("url is required").type
:configuration

decoding(message, opts \\ [])

@spec decoding(
  String.t(),
  keyword()
) :: t()

Builds a :decoding error.

Examples

iex> LiveKit.Error.decoding("malformed protobuf response").type
:decoding

encoding(message, opts \\ [])

@spec encoding(
  String.t(),
  keyword()
) :: t()

Builds an :encoding error.

Examples

iex> LiveKit.Error.encoding("request is not a protobuf struct").type
:encoding

http(message, opts \\ [])

@spec http(
  String.t(),
  keyword()
) :: t()

Builds an :http error for a non-success response without a Twirp payload.

Server-side statuses (5xx) plus 408 and 429 are marked retryable.

Examples

iex> LiveKit.Error.http("bad gateway", status: 502).retryable
true

new(opts)

@spec new(keyword()) :: t()

Builds an error.

:type and :message are required; everything else is optional. :meta is always passed through sanitize/1.

Examples

iex> error = LiveKit.Error.new(type: :validation, message: "ttl must be positive")
iex> {error.type, error.retryable}
{:validation, false}

sanitize(struct)

@spec sanitize(term()) :: term()

Removes credentials from an arbitrary metadata map.

Keys matching well-known credential names are dropped entirely, and values that look like a JWT (three base64url segments separated by .) are replaced with "[REDACTED]". Nested maps and lists are sanitized recursively.

Examples

iex> LiveKit.Error.sanitize(%{"api_secret" => "s3cret", "room" => "lobby"})
%{"room" => "lobby"}

iex> LiveKit.Error.sanitize(%{"detail" => "Bearer eyJhbGciOiJIUzI1NiJ9.eyJhIjoxfQ.sig"})
%{"detail" => "[REDACTED]"}

timeout(message, opts \\ [])

@spec timeout(
  String.t(),
  keyword()
) :: t()

Builds a :timeout error. Timeouts are retryable by default.

Examples

iex> LiveKit.Error.timeout("receive timeout").retryable
true

transport(message, opts \\ [])

@spec transport(
  String.t(),
  keyword()
) :: t()

Builds a :transport error. Transport failures are retryable by default.

Examples

iex> LiveKit.Error.transport("connection refused").retryable
true

twirp(message, opts \\ [])

@spec twirp(
  String.t(),
  keyword()
) :: t()

Builds a :twirp error from a decoded Twirp JSON error body.

Examples

iex> error = LiveKit.Error.twirp("room not found", code: "not_found", status: 404)
iex> {error.code, error.retryable}
{"not_found", false}

validation(message, opts \\ [])

@spec validation(
  String.t(),
  keyword()
) :: t()

Builds a :validation error.

Examples

iex> LiveKit.Error.validation("ttl must be positive").type
:validation