Erros de API de IA: 401, 403, 429 e 5xx
Diagnostique autenticação, políticas, limites, cancelamentos e falhas upstream por camada, decidindo quando repetir com segurança.
Um estado HTTP inicia o diagnóstico de uma API de IA, mas não contém a causa completa. Antes de repetir, preserve ID, hora UTC, endpoint, modelo, nome da chave, grupo, erro estruturado e tempos. Depois identifique se a rejeição veio do cliente, autenticação, política, protocolo, rota, backend ou ligação downstream.
Leitura inicial
| Estado | Primeira interpretação | Primeira ação |
|---|---|---|
| 400 | Payload ou contrato inválido | Corrigir, não repetir igual |
| 401 | Credencial ausente, inválida ou expirada | Rever Authorization e chave atual |
| 403 | Política de conta, modelo, grupo ou IP | Verificar limites antes dos canais |
| 404 | Caminho ou modelo incorreto | Rever Base URL e /v1/models |
| 429 | Limite de quota, taxa ou rota | Localizar e aplicar espera limitada |
| 499 | Cliente cancelou antes do fim | Rever deadlines, abort, proxy e primeira saída |
| 502/503/504 | Resposta upstream, disponibilidade ou tempo | Guardar prova e usar repetição limitada |
Diagnóstico por camadas
401 surge normalmente antes do encaminhamento. Confirme Authorization: Bearer ..., estado da chave, host e segredos antigos no deploy. Nunca coloque a chave completa em logs ou tickets.
403 não prova rejeição do fornecedor. Limite de modelo, allowlist de IP, acesso a grupo ou política de conta podem atuar antes da escolha de canal. Consulte /v1/models com a mesma chave e o código exato.
Para 429, descubra se o limite é da chave, conta, grupo ou rota. Respeite Retry-After, use backoff exponencial com jitter e limite tentativas, duração e concorrência. Mais chaves não contornam necessariamente um limite da conta.
499 regista o fim da ligação downstream. Comece por Abort, browser, CDN, balanceador e proxy; compare a primeira saída efetiva. Um único registo não demonstra indisponibilidade do canal.
Decisão de repetir
- Pedido, credencial ou acesso inválido: corrija, não repita igual.
- Rate limit: backoff limitado apenas quando permitido.
- 502, 503 ou 504 temporário: só trabalho idempotente com orçamento estrito.
- Cancelamento: confirme que ainda é necessário e não duplica efeitos.
- Ferramentas ou escritas: exija idempotência na aplicação.
Cada tentativa pode criar trabalho e custo. Partilhe com segurança ID, hora, endpoint, streaming, modelo, grupo, estado, código e tempos; evite chave completa, prompt, resposta, body, email ou IP em claro. Depois consulte Encaminhamento fiável e Streaming.