Skip to content
AX Framework
Principle 07

Graceful Failure

When something goes wrong, the product should explain what happened, whether it is safe to retry, and what the agent can do next.

Why it matters

Humans recover from vague errors by trying things. Agents can too, but trial and error against a live product is slow and can cause side effects.

A specific error turns a dead end into a decision point. "Size 42 is out of stock; sizes 41 and 43 are available" lets the agent go back to the person with a real choice.

Examples

Good exampleIllustrative

An out-of-stock error includes a stable code, the item affected, whether retrying could help, and alternatives.

json
{
  "error": {
    "code": "variant_unavailable",
    "message": "TRAIL-RUNNER-42-BLK is out of stock.",
    "retryable": false,
    "suggestions": [
      { "action": "add_to_cart", "input": { "sku": "TRAIL-RUNNER-43-BLK" } },
      { "action": "notify_when_available", "input": { "sku": "TRAIL-RUNNER-42-BLK" } }
    ]
  }
}
Bad exampleIllustrative

Any failure returns HTTP 500 with the message "Something went wrong. Please try again."

Implementation guidance

  1. 1Define a stable error vocabulary and document every code.
  2. 2Mark each error as retryable or not, with a retry-after hint when relevant.
  3. 3Include suggested next actions using the same action names as your manifest.

Evaluation criteria

  • Errors have stable, documented codes.
  • Retryability is explicit.
  • Common errors suggest at least one recovery path.