# `ALLM.Error.SpeechAdapterError`
[🔗](https://github.com/cykod/ALLM/blob/v0.6.1/lib/allm/error/speech_adapter_error.ex#L1)

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

| Reason | HTTP status | Fires when |
|--------|-------------|------------|
| `:authentication_failed` | 401/403 | API key missing or invalid. Surface to the user; no retry. |
| `:rate_limited` | 429 | Provider quota exceeded; `:retry_after_ms` populated when a `Retry-After` header is present. Retried automatically. |
| `:invalid_request` | 400/404/413 | Request shape rejected, or an empty `:input` reaching a direct adapter call. `:metadata` carries the detail. Fix the request; no retry. |
| `:context_length_exceeded` | 400 | `:input` is longer than the provider accepts; `:metadata` carries `:count` and `:max` when the adapter gates locally. Split the text; no retry. |
| `:provider_unavailable` | 5xx | Provider 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. |
| `:unknown` | any | Catch-all for shapes the adapter cannot classify; non-retryable. |

# `reason`

```elixir
@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`

```elixir
@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
}
```

# `legal_reasons`

```elixir
@spec legal_reasons() :: [reason()]
```

Return the closed list of legal `:reason` atoms.

## Examples

    iex> :context_length_exceeded in ALLM.Error.SpeechAdapterError.legal_reasons()
    true

    iex> :unsupported_feature in ALLM.Error.SpeechAdapterError.legal_reasons()
    true

    iex> length(ALLM.Error.SpeechAdapterError.legal_reasons())
    10

# `new`

```elixir
@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
`t: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

---

*Consult [api-reference.md](api-reference.md) for complete listing*