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

Copy Markdown View Source

Errors returned by ALLM.Adapter / ALLM.StreamAdapter implementations.

Layer A — serializable (no PIDs, refs, funs, or raw API keys). Refines spec §20's atom taxonomy into a struct so provider adapters report failures with uniform shape.

See Phase 1 design §Sub-phase 1.1 for the closed reason enum.

Error reasons

ReasonFires when
:rate_limitedProvider returned a rate-limit signal (HTTP 429, provider-specific header).
:authentication_failedCredentials rejected (HTTP 401/403).
:invalid_requestProvider rejected the request shape (HTTP 400).
:provider_unavailableProvider-side outage (HTTP 5xx, connection refused).
:context_length_exceededPrompt + expected output exceeds model context window.
:content_filterProvider refused content on policy grounds.
:timeoutRequest-level timeout (opts[:request_timeout] exceeded).
:network_errorTransport-level failure (DNS, TCP, TLS).
:malformed_responseProvider returned unparseable body.
:unsupported_featureModel or provider does not support a requested capability.
:no_scripted_responseTesting adapters (e.g., ALLM.Providers.Fake) exhausted their script. Never produced by production providers (spec §31, Phase 4 amendment).
:unknownCatch-all when no other reason fits; original term preserved in :cause.

Summary

Types

reason()

Closed set of adapter-level error reasons (spec §20).

t()

Functions

legal_reasons()

Return the closed list of legal :reason atoms.

new(reason, opts \\ [])

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

Types

reason()

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

Closed set of adapter-level error reasons (spec §20).

t()

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

Functions

new(reason, opts \\ [])

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

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

opts may include :message, :provider, :status, :retry_after_ms, :request_id, :cause, and :metadata. When :message is omitted, the default is "adapter error: #{reason}" — with a provider suffix "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.AdapterError.new(:timeout)
iex> err.reason
:timeout
iex> Exception.message(err)
"adapter error: timeout"

iex> err = ALLM.Error.AdapterError.new(:rate_limited, provider: :openai, retry_after_ms: 500)
iex> err.retry_after_ms
500
iex> Exception.message(err)
"adapter error (openai): rate_limited"