API errors

Every API error uses the same envelope, in REST and in MCP. The codes are the stable part; the text of message is written in Spanish, is meant for people and may change.

{  "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: Do not retry the request: it will not work on its own.
• as_is: Retry the SAME request, with the same idempotency key, after Retry-After if there is one.
• after_fixing: First fix what message and param say, then retry.

New codes can appear without changing the API version. Your code must not use a closed switch over error.code: handle an unknown code by its HTTP status and by 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();
  }
}

What to do with a code you do not know

• 400, 404, 409, 413 and 422: do not retry on your own; show the message or escalate to a person.
• 401 and 403: check the key and the permissions.
• 429 and 5xx: retry the same request with the same idempotency key, with growing waits.

Today there are 53 codes, grouped by HTTP status.