# AX-SYS-14: Diseña para el fallo elegante

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

Cuando algo falla, ofrece lógica de reintento, una ruta alternativa y un mensaje claro sobre el que el agente o la persona puedan actuar.

## Por qué

Los agentes necesitan errores recuperables, no callejones sin salida. Speakeasy identifica la recuperabilidad como una de las cuatro propiedades fundamentales de AX: los agentes que operan de forma autónoma no pueden mostrar un error a una persona y esperar; deben poder interpretar el error, determinar si un reintento es seguro y encontrar una ruta alternativa. Un `500 Internal Server Error` opaco termina por completo el flujo de trabajo del agente. Un error estructurado con `retryable: true`, `retry_after_seconds` y una ruta `alternative` convierte un fallo en un estado recuperable.

## Haz

Devuelve un error estructurado junto con un siguiente paso sugerido.

## No hagas

Devolver un 500 opaco.

## Artefacto

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

## Fuentes

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)