Diseña para el fallo elegante

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

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