Skip to content
AX Framework
Feedback pattern

Error Reporting

Return errors with stable codes, precise causes, retry guidance, and suggested next actions.

Problem

Generic errors force agents into guesswork. They retry things that will never succeed, give up on things that would, or report vague failures to people.

Context

Use this pattern when:

  • Any action can fail.
  • Agents need to decide what to do next without human help in most cases.

Recommended solution

Use a consistent error envelope across all actions, based on an established format such as RFC 9457 (Problem Details for HTTP APIs) and extended with AX fields: a stable code, the field or resource involved, whether the error is retryable, a retry-after hint, and suggested next actions.

  1. 01Adopt a single error format across the product.
  2. 02Document every error code.
  3. 03Mark retryability explicitly.
  4. 04Suggest recovery actions using manifest action names.

Interaction diagram

Interaction diagram for Error Reporting. 1. AI agent to Product · AX layer: apply_coupon(AUTUMN10). 2. Product · AX layer to AI agent: 422 coupon_expired, retryable: false. 3. AI agent to AI agent: Skip coupon, continue checkout.AI agentProduct · AX layerapply_coupon(AUTUMN10)1422 coupon_expired, retryable: false2Skip coupon, continue checkout
request response internal step

Example implementation

Illustrative example

Examples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.

application/problem+jsonjson
{
  "type": "https://northwind.example/errors/coupon_expired",
  "title": "Coupon expired",
  "status": 422,
  "detail": "AUTUMN10 expired on 2026-09-30.",
  "code": "coupon_expired",
  "field": "couponCode",
  "retryable": false,
  "suggestions": [{ "action": "list_active_promotions" }]
}

Accessibility and security

Accessibility

  • Errors written precisely for agents become precise error messages for people too.

Security

  • Do not leak internal details such as stack traces or SQL in error responses.
  • Avoid errors that reveal whether other users' resources exist.

Applies the principles Graceful Failure and Verifiable Outcomes.