ALLM.Error.ImageAdapterError exception (allm v0.3.0)

Copy Markdown View Source

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

ReasonHTTP statusFires when
:authentication_failed401API key missing or invalid.
:rate_limited429Provider quota exceeded; :retry_after_ms populated when a Retry-After header is present.
:invalid_request400Request shape rejected (unsupported size, invalid prompt, etc.).
:content_filter400Provider safety system rejected the prompt or output.
:context_length_exceeded400Textual prompt exceeds the model's context window.
:provider_unavailable5xxProvider 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.
:unknownanyCatch-all for shapes the adapter cannot classify; non-retryable.

Summary

Types

reason()

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

t()

Functions

legal_reasons()

Return the closed list of legal :reason atoms.

new(reason, opts \\ [])

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

Types

reason()

@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()

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

Functions

new(reason, opts \\ [])

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