Erros da API

Todos os erros da API usam o mesmo envelope, em REST e em MCP. Os códigos são a parte estável; o texto de message está em espanhol, é para pessoas e pode mudar.

{  "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: Não repita a requisição: não vai funcionar sozinha.
• as_is: Repita a MESMA requisição, com a mesma chave de idempotência, depois de Retry-After se houver.
• after_fixing: Corrija primeiro o que dizem message e param, e então repita.

Podem aparecer códigos novos sem mudar a versão da API. Seu código não deve usar um switch fechado sobre error.code: trate um código desconhecido pelo status HTTP e 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();
  }
}

O que fazer com um código que você não conhece

• 400, 404, 409, 413 e 422: não repita sozinho; mostre a mensagem ou escale para uma pessoa.
• 401 e 403: confira a chave e as permissões.
• 429 e 5xx: repita a mesma requisição com a mesma chave de idempotência, com espera crescente.

Hoje há 53 códigos, agrupados por status HTTP.