Lição 3 de 4 · 8 minutos

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.

StatusCódigo comumO que fazer
400validation_error, model_requiredCorrija a solicitação. error.param indica o campo.
401unauthorisedConfira a chave e o cabeçalho Authorization.
402insufficient_fundsAdicione créditos ou use phaseo/free.
403guardrail_blockedMude a solicitação ou o guardrail.
404not_foundConfira o caminho e o ID.
410model_retiredTroque para replacement_model.
429rate_limit_exceeded, key_limit_exceededAguarde Retry-After e tente de novo.
5xxupstream_error, gateway_errorRepita 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 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

Decida por error.code e pelo status, corrija os erros 4xx e repita com backoff só os 429 e os 5xx seguros.

Links relacionados

O progresso fica salvo neste navegador.

Verificado em 17 de novembro de 2026