Runtime errors

When a request through the Axiom runtime fails, you get a structured AxiomError instead of a bare exception. This page lists its fields and values, how to handle them, typed business failures, and the ADB codes the database commands print.

The AxiomError object

Match on code or category, never on message. Keep an unknown fallback so a newer runtime does not break an older UI.

How each binding exposes the object:

Compare stage and category without regard to case. Generated TypeScript or Dart types are authoritative for exact casing.

Codes added by the atmx-web JavaScript layer (0.147.5):

Stages

A failure's stage tells you where in the request it stopped:

Diagram source

flowchart LR
  L["Load contract: ContractLoad"] --> B["Build request: RequestBuild, ValidationRequest"]
  B --> R["Read cache: CacheRead"]
  R --> S["Send: NetworkSend"]
  S --> V["Receive: NetworkReceive"]
  V --> D["Validate and decode: ValidationResponse, Deserialize"]
  D --> W["Write cache: CacheWrite"]

Not every request passes every stage; a cache-only read stops early. Three stages sit outside the request path: Configuration (runtime or contract configuration), Runtime (engine lifecycle or internal execution), and FfiBoundary (the native or WebAssembly binding).

Categories

The categories are Contract, Validation, Network, Timeout, Serialization, Cache, Auth, Server, Runtime, and Unknown. A category is broader than a code: several HTTP statuses can map to Auth or Server.

Codes

Lower-level numeric FFI status values can merge several codes into one. Use the structured error your binding emits instead of copying a numeric table.

Handle errors

function messageFor(error: AxiomError): string {
  if (error.category.toLowerCase() === 'auth') return 'Please sign in again.';
  if (error.retryable) return 'Request failed. Try again.';
  if (error.code === 'ContractInvalid') {
    return 'This application release has an invalid data contract.';
  }
  return 'Something went wrong.';
}

Keep detailed diagnostic context in protected logs, not in a message the user sees.

Retry rules

• Retry only when retryable is true or your application policy explicitly allows it.
• Cap attempts and add jitter for network retries.
• Do not retry an invalid contract, unknown endpoint, request validation error, or deterministic decoding failure without changing the input or the deployment.
• Refresh or clear credentials before retrying an authentication failure.
• Treat cache errors separately: a cache write failure is not a failed server operation.

Typed failures and execution aborts

A managed action declares named failure cases, each with a payload and an HTTP status. The endpoint chooses which payload fields each audience may see. The HTTP failure body carries only error.code and the selected error.payload.

• Malformed envelopes and unknown cases are sanitized into transport errors.
• Execution aborts (cancellation, deadline, budget, host fault, and an indeterminate outcome) stay separate from recoverable business cases.
• New payload contracts need the version 2 contract reader.

The backend declaration catalog (axiom explain --schema) lists these failure categories: invalidInput, unauthenticated, forbidden, domain, invariant, policyExhausted, cancelled, deadline, internal, and indeterminate. See Managed logic and concurrency.

Database lifecycle codes (ADB)

The database commands (axiom database, axiom run on a database source) and the backend storage compiler print these codes.

See Database contracts and axiom database.

Other diagnostic code families