Skip to content
AX Framework

Implementation

Error Handling

Error formats, retryability, and recovery suggestions.

Agents meet more errors than people do: longer sessions, more steps, more rate limits, more stale data. Whether a task survives depends on whether each error tells the agent what happened and what to do next.

The error envelope

Build on RFC 9457 (Problem Details for HTTP APIs), an established IETF format, and add a few AX fields:

RFC 9457 AX extensions
json
{
  "type": "https://northwind.example/errors/insufficient_stock",
  "title": "Insufficient stock",
  "status": 409,
  "detail": "Only 2 units of TRAIL-RUNNER-42-BLK are available; 3 were requested.",
  "instance": "/actions/add_to_cart/req_7a1",

  "code": "insufficient_stock",
  "field": "quantity",
  "retryable": false,
  "context": { "available": 2, "requested": 3 },
  "suggestions": [
    { "action": "add_to_cart", "input": { "sku": "TRAIL-RUNNER-42-BLK", "quantity": 2 }, "label": "Add the 2 available" },
    { "action": "notify_when_available", "input": { "sku": "TRAIL-RUNNER-42-BLK" } }
  ]
}
FieldPurpose
codeStable, documented identifier agents can branch on
fieldThe input that caused the error, if any
retryableWhether the same request could succeed later
retryAfterSeconds to wait, for retryable errors
contextStructured values relevant to recovery
suggestionsNext actions, using names from the manifest

A vocabulary of codes

Keep a documented list. Most products need fewer than thirty codes. Group them by recovery strategy:

GroupExamplesAgent strategy
Inputvalidation_failed, ambiguous_inputFix input or ask the principal
Stateinvalid_state, version_conflict, expiredRe-read state, then retry or re-plan
Authorityinsufficient_scope, approval_required, limit_exceededRequest scope or approval
Availabilityinsufficient_stock, slot_unavailableChoose an alternative
Transientrate_limited, temporarily_unavailableWait and retry
Fatalnot_supported, account_suspendedStop and report

Status codes

Use HTTP status codes honestly. Never return 200 with an error in the body.

SituationStatus
Validation error422
Missing scope403
Version conflict409 or 412
Rate limited429 with Retry-After
Temporarily unavailable503 with Retry-After
Payment required or declined402

Clarification is not an error

When input is ambiguous, ask rather than guess. Return a clarification response with options:

json
{
  "status": "needs_clarification",
  "field": "destination",
  "message": "More than one place matches “Portland”.",
  "options": [
    { "id": "PDX", "label": "Portland, Oregon, United States" },
    { "id": "PWM", "label": "Portland, Maine, United States" }
  ]
}

Writing messages

The detail message is often relayed to a person. Write it for them:

  • Say what happened, specifically: "Only 2 units are available", not "Stock error".
  • Avoid blame and jargon.
  • Never include stack traces, SQL, or internal hostnames.

Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.