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.
- 01Adopt a single error format across the product.
- 02Document every error code.
- 03Mark retryability explicitly.
- 04Suggest recovery actions using manifest action names.
Interaction diagram
Example implementation
Illustrative exampleExamples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.
{
"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.
Related patterns
Applies the principles Graceful Failure and Verifiable Outcomes.