Quando uma solicitação falha
Decida pelo código de erro e pelo status, e repita só os erros que podem dar certo depois.
Todo erro do Phaseo tem o mesmo corpo JSON em todos os endpoints. O objeto error tem a forma que os SDKs compatíveis com OpenAI já leem:
{
"error": {
"code": "insufficient_funds",
"message": "...",
"type": "insufficient_quota",
"param": null
},
"generation_id": "G-...",
"status_code": 402
}
Decida com base em error.code e no status HTTP, nunca no texto da mensagem. Sempre registre generation_id.
| Status | Código comum | O que fazer |
|---|---|---|
400 | validation_error, model_required | Corrija a solicitação. error.param indica o campo. |
401 | unauthorised | Confira a chave e o cabeçalho Authorization. |
402 | insufficient_funds | Adicione créditos ou use phaseo/free. |
403 | guardrail_blocked | Mude a solicitação ou o guardrail. |
404 | not_found | Confira o caminho e o ID. |
410 | model_retired | Troque para replacement_model. |
429 | rate_limit_exceeded, key_limit_exceeded | Aguarde Retry-After e tente de novo. |
5xx | upstream_error, gateway_error | Repita com backoff. |
Não repita sem mudanças os erros 4xx além do 429: eles falham de novo. Para 429, aguarde Retry-After (segundos ou uma data HTTP) ou use backoff exponencial com jitter. Um key_limit_exceeded sem Retry-After não volta ao normal sozinho, então não o repita. Repita 5xx só quando for seguro refazer a chamada, e defina um limite de tentativas e um prazo total.
Confira o que você aprendeu
A sua solicitação retorna 401 com o código unauthorised. O que o seu código deve fazer?
Aplique
Um script em lote envia 500 solicitações em um loop. Na metade, as respostas começam a voltar como 429 com o cabeçalho Retry-After: 20. O que você muda?
Mostrar a respostaOcultar a resposta
Faça o script respeitar Retry-After: espere uns 20 segundos antes de tentar de novo e use backoff exponencial com jitter quando o cabeçalho não vier. Confira também error.code: rate_limit_exceeded volta ao normal, mas um key_limit_exceeded sem Retry-After não, então repeti-lo é inútil.
Resumo
error.code e pelo status, corrija os erros 4xx e repita com backoff só os 429 e os 5xx seguros.Links relacionados
Verificado em 17 de novembro de 2026