ALLM.Error.ModerationAdapterError exception (allm v0.6.1)

Copy Markdown View Source

Errors returned by ALLM.ModerationAdapter implementations.

Layer A — serializable (no PIDs, refs, funs, or raw API keys). Closed-enum exception struct carrying the same eleven reasons as ALLM.Error.EmbeddingAdapterError.

Two atoms that appear on ALLM.Error.ImageAdapterError are deliberately absent. There is no :content_filter: a moderation call is never itself content-filtered — classifying harmful text is the endpoint's whole purpose. There is no :unsupported_operation either, for the same reason it is absent from the embeddings sibling — moderation has no operations enum.

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, an empty :input reaching a direct adapter call, an unsupported image type, or an image over the provider's size cap. :metadata carries the specific detail. Fix the request; no retry.
:context_length_exceeded400A single input exceeds the model's token limit. Shorten it; 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 a results entry missing its verdict. No retry; file a bug.
:unsupported_feature—Request used a field this adapter cannot express; metadata.feature names it. No retry.
:batch_too_large—the request's item count exceeds ALLM.ModerationAdapter.max_batch_size/0; metadata carries :count and :max. ALLM.moderate/3 does NOT chunk, so this IS reachable through the façade — recover by chunking the input yourself.
:unknownanyCatch-all for shapes the adapter cannot classify; non-retryable.

Summary

Types

reason()

Closed set of moderation-adapter error reasons.

t()

Functions

legal_reasons()

Return the closed list of legal :reason atoms.

new(reason, opts \\ [])

Build a %ModerationAdapterError{} 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 moderation-adapter error reasons.

t()

@type t() :: %ALLM.Error.ModerationAdapterError{
  __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 a %ModerationAdapterError{} 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 "moderation adapter error: #{reason}" — with a provider suffix "moderation 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.ModerationAdapterError.new(:timeout)
iex> err.reason
:timeout
iex> Exception.message(err)
"moderation adapter error: timeout"

iex> err = ALLM.Error.ModerationAdapterError.new(:batch_too_large, metadata: %{count: 500, max: 32})
iex> err.metadata.max
32