Erros de API de IA: 401, 429, 5xx e tempos limite
Separe autenticação, cota, limites de solicitações e falhas transitórias nas APIs OpenAI, Claude e Gemini. Use os detalhes do erro antes de decidir tentar novamente.
Resposta rápida
Um erro de API não comprova, por si só, uma interrupção do provedor. Leia o corpo do erro e o ID da solicitação do provedor e verifique o componente de status correspondente. Problemas de autenticação e cobrança exigem mudanças de configuração; falhas transitórias podem justificar novas tentativas limitadas.
Comece pela categoria do erro
Use esta tabela para escolher uma primeira verificação. Os significados e soluções exatos dependem do provedor, endpoint e corpo do erro.
| O que você vê | Primeira verificação | O que não estabelece |
|---|---|---|
| 400 / 404 / 413 | Formato da solicitação, endpoint, recurso e tamanho; leia o erro do provedor | Uma interrupção geral do serviço |
| 401 / 403 | Credenciais, permissões de acesso e restrições específicas do provedor | Que todos os usuários estão bloqueados |
| 429 | Cabeçalhos de limites de solicitações, cota, créditos e limites de gastos | Que tentar novamente imediatamente funcione |
| 500 / 503 / 529 | Detalhes do erro do provedor e componente oficial relevante | Um incidente global confirmado |
| Tempo limite / erro de conexão | Prazo do cliente, DNS, TLS, proxy e duração da solicitação | Qual lado causou a falha |
OpenAI: um 429 pode significar limites diferentes
Examine error.code, não apenas HTTP 429. OpenAI distingue limites de frequência de solicitações de créditos esgotados e limites da organização ou projeto. Falhas de cobrança e cota não são corrigidas por novas tentativas. Para limites transitórios ou sobrecarga, respeite Retry-After quando presente e limite as tentativas.
Use a entrada OpenAI API para componentes API. A entrada do aplicativo ChatGPT não confirma o resultado de uma solicitação API ou a integridade de um modelo GPT específico.
Claude: sobrecarga e limites de gastos são diferentes
Claude documenta 529 como sobrecarga, 401 como falha de autenticação e 403 como falha de permissão. Um 429 pode refletir limites de solicitações ou um limite de gastos. Um 429 por limite de gastos do nível de uso não inclui cabeçalho Retry-After e continua falhando até o acesso ser retomado. Leia o erro completo antes de selecionar uma política de novas tentativas.
Para respostas em fluxo, Claude documenta que um erro pode ocorrer após HTTP 200. Verifique a conclusão e os eventos de erro do fluxo; receber apenas os cabeçalhos de resposta não comprova uma geração bem-sucedida.
Gemini: verifique o endpoint para desenvolvedores
Google recomenda espera exponencial limitada com variação aleatória para falhas transitórias. Verifique também a versão da API, o modelo e os parâmetros compatíveis. Consulte o relatório próprio da API para desenvolvedores; o feed de incidentes do aplicativo Gemini não abrange solicitações de Gemini API ou AI Studio.
Defina um orçamento para novas tentativas
Como decisão de projeto do aplicativo, defina um número máximo de tentativas e um limite total de tempo. Considere as novas tentativas já feitas pelo SDK. Use um atraso com espera exponencial e variação aleatória para erros identificados pelo provedor como transitórios e respeite os cabeçalhos de nova tentativa aplicáveis.
Antes de repetir uma solicitação interrompida, verifique se ela já pode ter produzido saída, cobrança ou uma ação posterior. Repetir uma solicitação de modelo e uma ação de ferramenta de um agente são decisões separadas. Preserve os IDs de solicitação para investigação e interrompa as novas tentativas automáticas quando o orçamento permitido acabar.
Investigue uma resposta específica
Use um guia dedicado ao erro retornado pela solicitação. Estas páginas explicam falhas de solicitações; não monitoram limites de conta.
Páginas de serviços relacionados
Cada entrada mostra sua própria cobertura de coleta. Um serviço com link não é necessariamente coletado automaticamente.
A data de revisão editorial se aplica a este guia. As horas de coleta dos relatórios atuais aparecem nas páginas dos serviços.