# AX-SYS-14: Design for graceful failure

> Recovery and reliability · foundational · AX-SYS-14

When something breaks, return retry logic, an alternate path, and a clear message the agent or user can act on.

## Why

Agents need recoverable errors, not dead ends. Speakeasy identifies Recoverability as one of four foundational AX properties: agents operating autonomously cannot surface an error to a human and wait — they must be able to parse the error, determine if a retry is safe, and find an alternate path. An opaque `500 Internal Server Error` ends the agent's workflow entirely. A structured error with `retryable: true`, `retry_after_seconds`, and an `alternative` path turns a failure into a recoverable state.

## Do

Return a structured error plus a suggested next step.

## Don't

Return an opaque 500.

## Artifact

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "retryable": true,
    "retry_after_seconds": 30,
    "alternative": "Use GET /v1/orders/export for bulk reads.",
    "docs": "https://acme.com/docs/limits.md"
  }
}
```

## Citations

1. [Speakeasy — Designing Agent Experience](https://www.speakeasy.com/blog/agent-experience-introduction) — Recoverability is one of four foundational AX properties: agents need structured, actionable errors — not dead ends — to self-correct and continue on behalf of the user
2. [Anthropic — Building Effective AI Agents](https://www.anthropic.com/research/building-effective-agents) — Agents operating in automated pipelines need clear, recoverable error signals; opaque failures cause agents to retry incorrectly or halt entirely
3. [MCP Specification 2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) — MCP error responses must be structured and machine-readable; the protocol defines standard error codes and expects servers to include recoverable context

---
Source: Agent Experience Principles (axprinciples.com)