Errors and HTTP mapping

AshOnetime.Error is a Splode error of class :invalid, so Ash recognizes it and preserves it through the action pipeline. When a protected action fails, the typed :code reaches the caller — either as the leaf error directly (single error) or inside Ash.Error.Invalid{errors: [...]} (multiple errors) — instead of being wrapped as an unknown error.

Reading the code

AshOnetime.Error.code/1 recovers the typed code from whatever Ash hands the caller, without pattern-matching the wrapper shape:

case Ash.create(changeset) do
  {:ok, record} -> record
  {:error, error} ->
    case AshOnetime.Error.code(error) do
      :nonce_already_used -> {:conflict, "nonce was already used"}
      :key_reused_with_different_request -> {:conflict, "key reused with a different request"}
      :request_in_progress -> {:conflict, "request is already processing"}  # 425 Too Early also fits
      :verification_failed -> {:unauthorized, "verification failed"}
      :verification_timeout -> {:service_unavailable, "verification timed out"}
      nil -> {:internal_server_error, "unexpected error"}  # not an ash_onetime error
    end
end

code/1 returns nil for any value that is not an AshOnetime.Error and contains no AshOnetime.Error leaf — so "ash_onetime rejected this with a known code" is cleanly distinguishable from "some other error occurred."

Class and HTTP

All AshOnetime.Error codes are class :invalid. AshJsonApi and AshGraphql auto-map class :invalid to the 4xx family. That default is correct for the client-input codes below, but a family of server-fault and transport codes overrides it to 5xx — a consumer mapping class→HTTP must special-case those (the two 5xx tables below), or a store outage, a trusted clock fault, or an internal invariant violation is mis-reported to the client as a 4xx.

This page lists every code a caller can observe from AshOnetime.Error.code/1, including the token-verification codes, the trusted-clock codes, and the store-fault/transport codes routed through the authoritative store — not only the codes raised on the happy admission path.

Client-input / operational codes (4xx)

Server-fault codes (5xx — override the class default)

These are NOT client input. A consumer mapping class→HTTP to a blanket 4xx would mis-categorize them; the per-code HTTP below overrides the :invalid class.

Store-fault and transport codes (5xx — override the class default)

When the authoritative PostgreSQL store is unavailable or reports a fault, admission fails closed (nonces always; idempotency unless untracked execution is explicitly enabled) and the store's reason surfaces verbatim through AshOnetime.Error.code/1. A generic :store_failure covers any reason not enumerated below. Treat the 503 codes as retryable (the request may succeed on retry once the store recovers) and the 500 codes as integrity or configuration faults that will not clear by retrying.

details and classified data

The details map is part of the error struct and reaches sinks that serialize or inspect the struct — inspect(error) in logs is the present-tense sink, and any future AshJsonApi/AshGraphql integration renders struct fields into HTTP/API responses. (Note: Exception.message/1 and Ash.Error.error_descriptions/1 render only the message field, not details — but details is still on the struct and should be treated as renderable-to-callers.) Never put key material, tokens, payloads, signatures, or PII in details.

The library's own call sites populate details only with non-secret context — field or option names (atoms) and numeric byte limits (e.g. %{field: :key_id, maximum: 128}). One path carries application-supplied data: when an application's key resolver returns {:error, reason}, ash_onetime wraps it as Error.new(:key_resolution_failed, ..., %{reason: reason}) (lib/ash_onetime/token.ex). A resolver that returns key material in its error reason would leak it through the rendered error. Keep resolver error reasons secret-free — return an atom or a generic message, not the key. (Audited at this release; re-audit any future call site that adds details.)