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{
"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" } }
]
}| Field | Purpose |
|---|---|
code | Stable, documented identifier agents can branch on |
field | The input that caused the error, if any |
retryable | Whether the same request could succeed later |
retryAfter | Seconds to wait, for retryable errors |
context | Structured values relevant to recovery |
suggestions | Next 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:
| Group | Examples | Agent strategy |
|---|---|---|
| Input | validation_failed, ambiguous_input | Fix input or ask the principal |
| State | invalid_state, version_conflict, expired | Re-read state, then retry or re-plan |
| Authority | insufficient_scope, approval_required, limit_exceeded | Request scope or approval |
| Availability | insufficient_stock, slot_unavailable | Choose an alternative |
| Transient | rate_limited, temporarily_unavailable | Wait and retry |
| Fatal | not_supported, account_suspended | Stop and report |
Status codes
Use HTTP status codes honestly. Never return 200 with an error in the body.
| Situation | Status |
|---|---|
| Validation error | 422 |
| Missing scope | 403 |
| Version conflict | 409 or 412 |
| Rate limited | 429 with Retry-After |
| Temporarily unavailable | 503 with Retry-After |
| Payment required or declined | 402 |
Clarification is not an error
When input is ambiguous, ask rather than guess. Return a clarification response with options:
{
"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.
Related
Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.