ALLM.Error.SpeechAdapterError exception (allm v0.6.1)

Copy Markdown View Source

Errors returned by speech-synthesis adapters.

Layer A — serializable (no PIDs, refs, funs, or raw API keys). A closed-enum exception struct with ten reasons.

There is no :batch_too_large: a speech request carries one input, and there is no multi-input form to overflow. There is no :content_filter, which only the transcription sibling ALLM.Error.TranscriptionAdapterError carries.

Error reasons

ReasonHTTP statusFires when
:authentication_failed401/403API key missing or invalid. Surface to the user; no retry.
:rate_limited429Provider quota exceeded; :retry_after_ms populated when a Retry-After header is present. Retried automatically.
:invalid_request400/404/413Request shape rejected, or an empty :input reaching a direct adapter call. :metadata carries the detail. Fix the request; no retry.
:context_length_exceeded400:input is longer than the provider accepts; :metadata carries :count and :max when the adapter gates locally. Split the text; no retry.
:provider_unavailable5xxProvider server-side failure. Retried automatically.
:timeout—Adapter request_timeout exceeded. Retried automatically.
:network_error—TCP/TLS/DNS failure. Retried automatically.
:malformed_response—200 without the expected audio payload. No retry; file a bug.
:unsupported_feature—The request sets a field the adapter's provider cannot express (for example :instructions, a :format it cannot produce, or a :sample_rate outside the format's set). Refused locally, before the API key is resolved. Drop or change the field; no retry.
:unknownanyCatch-all for shapes the adapter cannot classify; non-retryable.

Summary

Types

reason()

Closed set of speech-adapter error reasons.

t()

Functions

legal_reasons()

Return the closed list of legal :reason atoms.

new(reason, opts \\ [])

Build a %SpeechAdapterError{} from a reason atom and optional keyword fields.

Types

reason()

@type reason() ::
  :authentication_failed
  | :rate_limited
  | :invalid_request
  | :context_length_exceeded
  | :provider_unavailable
  | :timeout
  | :network_error
  | :malformed_response
  | :unsupported_feature
  | :unknown

Closed set of speech-adapter error reasons.

t()

@type t() :: %ALLM.Error.SpeechAdapterError{
  __exception__: true,
  cause: term() | nil,
  message: String.t(),
  metadata: map(),
  provider: atom() | nil,
  reason: reason(),
  retry_after_ms: non_neg_integer() | nil,
  status: pos_integer() | nil
}

Functions

new(reason, opts \\ [])

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

Build a %SpeechAdapterError{} from a reason atom and optional keyword fields.

opts may include :message, :provider, :status, :retry_after_ms, :cause, and :metadata. When :message is omitted, the default is "speech adapter error: #{reason}" — with a provider suffix "speech adapter error (#{provider}): #{reason}" when :provider is set.

Raises ArgumentError if reason is not one of the atoms in the closed reason/0 enum.

Examples

iex> err = ALLM.Error.SpeechAdapterError.new(:timeout)
iex> err.reason
:timeout
iex> Exception.message(err)
"speech adapter error: timeout"

iex> err = ALLM.Error.SpeechAdapterError.new(:context_length_exceeded, metadata: %{count: 4097, max: 4096})
iex> err.metadata.max
4096