Códigos de erro
O que significam 401 / 403 / 404 / 429 / 5xx, uma triagem em cinco passos e práticas que evitam erros.
Quando uma chamada falha, comece pelo código de status HTTP e pela mensagem de erro no corpo da resposta, e compare com a tabela abaixo. A maioria dos problemas se resolve com os três primeiros itens.
Códigos de status
| Status | Significado | Causas e soluções comuns |
|---|---|---|
| 400 Bad Request | Requisição inválida | JSON malformado ou campo obrigatório ausente (model, messages); confira o corpo contra a documentação da API |
| 401 Unauthorized | Falha na autenticação | A chave está errada / foi excluída / expirou; veja a lista de verificação em Autenticação |
| 403 Forbidden | Sem acesso | Esta chave ou conta não pode chamar o modelo solicitado; confirme na vitrine que o modelo está disponível para você |
| 404 Not Found | Recurso inexistente | Normalmente é o ID do modelo escrito errado; copie o ID exato da vitrine de modelos |
| 429 Too Many Requests | Limite de requisições | As requisições estão muito frequentes. Recue (intervalos exponenciais) ou reduza a concorrência; fale com a plataforma se persistir |
| 5xx | Erro do lado do servidor | Falha temporária da plataforma ou do modelo upstream. Tente mais uma vez com os mesmos parâmetros; se continuar falhando, fale com o Suporte informando os registros de requisição da página de logs |
Passos de investigação
- Verifique a chave: confirme na página "Chaves de API" que a chave existe e não expirou; se tiver dúvida, exclua e crie outra.
- Verifique o ID do modelo: copie-o da vitrine de modelos em vez de digitá-lo à mão.
- Leia o corpo do erro: as respostas de erro geralmente trazem
error.messageexplicando a causa exata (saldo insuficiente, parâmetro ausente, ...). - Confira os logs: a página de logs do console mostra status, latência e consumo por requisição — verifique se a falha se limita a um modelo ou a uma chave.
- Ainda travado: fale com o Suporte informando os horários e códigos de status da página de logs.
Práticas que evitam erros
- Use um SDK oficial (ele cuida de retentativas, timeouts e detalhes de protocolo para você);
- Implemente backoff exponencial para 429 / 5xx em vez de insistir em retentativas;
- Defina um limite de gastos nas chaves de produção para que tráfego anormal não consuma todo o saldo.