Erros de API de IA: 401, 403, 429 e 5xx

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.

Verificações específicas por camada

Para 401

Confirme Authorization: Bearer ..., aspas ou espaços adicionais, estado da chave e segredos antigos no deployment. Este erro ocorre normalmente antes do encaminhamento do modelo.

Para 403

Com a mesma chave, reveja modelos autorizados, lista de IP, acesso ao grupo e política da conta. Se ainda não foi escolhido um canal, mudar de fornecedor não corrige a rejeição anterior.

Para 429

Determine se o limite pertence à chave, conta, grupo ou rota. Respeite Retry-After, use espera exponencial com variação e limite tentativas, duração total e concorrência.

Para 499

Comece pelo cliente: sinal de cancelamento, separador fechado, CDN, balanceador e limites do proxy. Compare o cancelamento com a primeira saída efetiva; um 499 isolado não prova indisponibilidade do canal.

Distinga os erros 5xx

500 pode ser uma falha determinística do adaptador, 502 uma resposta upstream inválida ou incompleta, 503 ausência temporária de rota e 504 esgotamento de um limite de tempo. Preserve o estado original e repita apenas operações seguras com limite estrito.

Provas seguras para diagnóstico

• ID do pedido e hora UTC;
• endpoint e modo de streaming;
• modelo pedido e grupo selecionado;
• estado HTTP e código de erro estruturado;
• tempo total e tempo até à primeira saída efetiva;
• indicação de cancelamento pelo cliente;
• descrição saneada de funções como ferramentas ou imagens.

Não inclua chave completa, prompt, resposta, body original, email ou IP em claro fora de um processo seguro expressamente aprovado.

Perguntas frequentes

Um 403 prova que o fornecedor está indisponível?

Não. Conta, chave, modelo, grupo, IP ou política de funções podem rejeitar o pedido antes da seleção do fornecedor.

Um 499 é um erro normal do modelo upstream?

Não. Nos registos da Modelflare representa um cancelamento downstream observado antes da conclusão.

Todos os 5xx devem ser repetidos?

Não. Repita apenas trabalho seguro, limite tentativas e tempo total e preserve sempre o primeiro erro.