Errores de la API

Todos los errores de la API usan el mismo sobre, en REST y en MCP. Los códigos son la parte estable; el texto de message está en español, es para personas y puede cambiar.

{  "ok": false,  "status": 400,  "request_id": "req_3z6y1wUd",  "error": {    "type": "invalid_request_error",    "code": "invalid_amount_format",    "message": "«abc» no es un monto válido. Usa un número positivo como texto con hasta 6 decimales, por ejemplo \"4.80\".",    "param": "amount",    "retry": "after_fixing",    "retry_after_ms": null,    "outcome_unknown": false  }}

• no: No repitas la petición: no va a funcionar sola.
• as_is: Repite la MISMA petición, con la misma llave de idempotencia, pasado Retry-After si lo hay.
• after_fixing: Corrige primero lo que dicen message y param, y entonces repite.

Pueden aparecer códigos nuevos sin cambiar la versión de la API. Tu código no debe usar un switch cerrado sobre error.code: trata un código desconocido por su estado HTTP y por error.retry.

function handleError(status: number, error: { code: string; retry: string }) {
  switch (error.code) {
    case 'rate_limited':
      return waitAndRetrySameRequest();
    default:
      // Código nuevo o desconocido: decide por error.retry y por el estado HTTP.
      return error.retry === 'as_is' ? retrySameRequest() : showMessage();
  }
}

Qué hacer con un código que no conoces

• 400, 404, 409, 413 y 422: no repitas solo; muestra el mensaje o escala a una persona.
• 401 y 403: revisa la llave y los permisos.
• 429 y 5xx: repite la misma petición con la misma llave de idempotencia, con espera creciente.

Hoy hay 53 códigos, agrupados por estado HTTP.