# `ALLM.Error.EmbeddingAdapterError`
[🔗](https://github.com/cykod/ALLM/blob/v0.5.0/lib/allm/error/embedding_adapter_error.ex#L1)

Errors returned by `ALLM.EmbeddingAdapter` implementations.

Layer A — serializable (no PIDs, refs, funs, or raw API keys). Closed-enum
exception struct mirroring `ALLM.Error.ImageAdapterError`'s shape with one
embeddings-specific atom (`:batch_too_large`) and without the two image-only
atoms (`:content_filter`, `:unsupported_operation`).

## 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 | Request shape rejected, or an empty `:input` reaching a direct adapter call. Fix the request; no retry. |
| `:context_length_exceeded` | 400 | A single input exceeds the model's token limit, or the batch exceeds a per-request token cap. Chunk smaller or shorten inputs; 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 with an unparseable body, or an entry whose vector is empty. No retry; file a bug. |
| `:unsupported_feature` | — | Request combined features the adapter cannot express (e.g. a reduced `:dimensions` on a model that has no such knob). `metadata.feature` carries the rejected field. No retry. |
| `:batch_too_large` | — | `length(request.input) > max_batch_size()`; `metadata` carries `:count` and `:max`. Unreachable through `ALLM.embed/3`, which chunks; recoverable by chunking. |
| `: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
  | :batch_too_large
  | :unknown
```

Closed set of embedding-adapter error reasons.

# `t`

```elixir
@type t() :: %ALLM.Error.EmbeddingAdapterError{
  __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> :batch_too_large in ALLM.Error.EmbeddingAdapterError.legal_reasons
    true

    iex> length(ALLM.Error.EmbeddingAdapterError.legal_reasons)
    11

# `new`

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

Build an `%EmbeddingAdapterError{}` 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
`"embedding adapter error: #{reason}"` — with a provider suffix
`"embedding 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.EmbeddingAdapterError.new(:timeout)
    iex> err.reason
    :timeout
    iex> Exception.message(err)
    "embedding adapter error: timeout"

    iex> err = ALLM.Error.EmbeddingAdapterError.new(:batch_too_large, metadata: %{count: 3000, max: 2048})
    iex> err.metadata.max
    2048

---

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