# `ALLM.Error.ImageAdapterError`
[🔗](https://github.com/cykod/ALLM/blob/v0.3.0/lib/allm/error/image_adapter_error.ex#L1)

Errors returned by `ALLM.ImageAdapter` implementations.

Layer A — serializable (no PIDs, refs, funs, or raw API keys). See spec
§35.3. Closed-enum exception struct mirroring `ALLM.Error.AdapterError`'s
shape with one image-specific atom (`:unsupported_operation`).

See Phase 14.1 design Decision #4 for the closed reason enum and the
per-reason recovery table.

## Error reasons

| Reason | HTTP status | Fires when |
|--------|-------------|------------|
| `:authentication_failed` | 401 | API key missing or invalid. |
| `:rate_limited` | 429 | Provider quota exceeded; `:retry_after_ms` populated when a `Retry-After` header is present. |
| `:invalid_request` | 400 | Request shape rejected (unsupported size, invalid prompt, etc.). |
| `:content_filter` | 400 | Provider safety system rejected the prompt or output. |
| `:context_length_exceeded` | 400 | Textual prompt exceeds the model's context window. |
| `:provider_unavailable` | 5xx | Provider server-side failure; retryable. |
| `:timeout` | — | Adapter `request_timeout` exceeded. |
| `:network_error` | — | TCP/TLS/DNS failure. |
| `:malformed_response` | — | 200 with unparseable body. |
| `:unsupported_feature` | — | Request combined features the adapter cannot express. |
| `:unsupported_operation` | — | `request.operation not in supported_operations()`; `metadata.operation` carries the rejected atom. |
| `:unknown` | any | Catch-all for shapes the adapter cannot classify; non-retryable. |

# `reason`

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

Closed set of image-adapter error reasons (spec §35.3, Phase 14.1 Decision #4).

# `t`

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

    iex> length(ALLM.Error.ImageAdapterError.legal_reasons())
    12

# `new`

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

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

    iex> err = ALLM.Error.ImageAdapterError.new(:unsupported_operation, metadata: %{operation: :edit})
    iex> err.metadata.operation
    :edit

---

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