Design for graceful failure

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

{
  "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"
  }
}