ALLM.Error.EmbeddingAdapterError exception (allm v0.5.0)

Copy Markdown View Source

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

ReasonHTTP statusFires when
:authentication_failed401/403API key missing or invalid. Surface to the user; no retry.
:rate_limited429Provider quota exceeded; :retry_after_ms populated when a Retry-After header is present. Retried automatically.
:invalid_request400Request shape rejected, or an empty :input reaching a direct adapter call. Fix the request; no retry.
:context_length_exceeded400A 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_unavailable5xxProvider 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.
:unknownanyCatch-all for shapes the adapter cannot classify; non-retryable.

Summary

Types

reason()

Closed set of embedding-adapter error reasons.

t()

Functions

legal_reasons()

Return the closed list of legal :reason atoms.

new(reason, opts \\ [])

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

Types

reason()

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

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

Functions

new(reason, opts \\ [])

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