Guia de erros de API de IA: 401, 403, 429 e 5xx
Diagnostique falhas de autenticação, política de acesso, limites de taxa, cancelamento pelo cliente e erros do provedor, e saiba quando é seguro tentar novamente.

Erros de API de IA ficam mais fáceis de diagnosticar quando o código de status é tratado como o início da investigação, e não como a causa completa. Antes de tentar novamente, guarde o ID da solicitação, o horário, o endpoint, o modelo, o nome da chave de API, o grupo selecionado, o corpo da resposta e os tempos.
O objetivo é identificar qual camada rejeitou ou encerrou a solicitação: cliente, autenticação, política de acesso, validação de protocolo, roteamento, backend do modelo ou conexão com o cliente.
O que os códigos de status comuns costumam indicar
| Status | Primeira interpretação | Primeira ação |
|---|---|---|
| 400 | Formato da solicitação, campo ou contrato de protocolo inválido | Compare o payload com o endpoint selecionado; não tente novamente sem alterações |
| 401 | Credencial ausente, malformada, desativada, expirada ou inválida | Verifique o cabeçalho Authorization e a chave atual |
| 403 | Autenticado, mas bloqueado por conta, modelo, grupo, IP ou política | Verifique as restrições da chave e o acesso ao modelo e ao grupo antes de testar canais |
| 404 | Caminho de endpoint errado ou identificador de modelo indisponível | Verifique a URL base, o caminho e a lista autenticada de modelos |
| 429 | Limite de taxa de solicitações, de cota ou de rotas elegíveis | Verifique a cota e os limites do grupo; use backoff limitado ou a contingência configurada |
| 499 | O cliente se desconectou ou cancelou antes da conclusão | Verifique prazos do cliente, aborts, proxies e o tempo até a primeira saída |
| 500 | Falha no processamento interno ou no adaptador | Guarde o ID da solicitação; tente novamente apenas se a operação for segura |
| 502/503 | Resposta inválida do provedor, rota indisponível ou problema temporário de capacidade | Verifique as evidências da rota e use contingência ou novas tentativas limitadas |
| 504 | Um limite de tempo do gateway ou do provedor expirou | Compare os tempos até a primeira saída e total com os prazos do cliente |
Essas interpretações são pontos de partida para o diagnóstico. O corpo do erro e o registro da solicitação determinam o motivo real de cada chamada específica.
Diagnostique o 401 antes de trocar o modelo
Um 401 normalmente ocorre antes de qualquer roteamento útil do modelo. Verifique se:
- o cabeçalho usa Authorization: Bearer ...;
- a aplicação não incluiu aspas, espaços em branco ou um valor de exemplo;
- a chave está ativada e não expirou;
- a solicitação é enviada para o host correto do Modelflare;
- um gerenciador de segredos ou uma implantação não manteve uma chave antiga já rotacionada.
Não cole a chave completa em logs ou mensagens de suporte. Se houver risco de exposição, reproduza o problema com uma chave de teste dedicada e depois revogue a credencial comprometida.
Diagnostique o 403 primeiro como falha de política de acesso
Um 403 não significa automaticamente que o provedor rejeitou a solicitação. A autenticação pode ser bem-sucedida e o acesso falhar antes da seleção do canal porque:
- a chave restringe o modelo solicitado;
- a lista de IPs permitidos da chave não inclui o IP observado do cliente;
- a conta não pode usar o grupo de modelos selecionado;
- o usuário ou a chave foi desativado por política;
- o recurso solicitado não é permitido nessa rota.
Consulte /v1/models com a mesma chave, verifique os limites de grupo e de modelos dela e compare o código de erro exato. Se nenhum canal foi selecionado, trocar os canais do provedor não corrige a decisão de política tomada antes.
Diagnostique o 429 sem criar uma tempestade de novas tentativas
Um 429 é um sinal de capacidade ou de política, e não uma instrução para tentar novamente de imediato em um loop apertado. Descubra se o limite pertence à cota da chave, à conta, ao grupo de modelos ou à rota selecionada.
Para limites de taxa que admitem nova tentativa:
- respeite o Retry-After quando ele estiver presente;
- use backoff exponencial com jitter;
- limite o número de tentativas e o tempo total decorrido;
- mantenha a concorrência da aplicação dentro de um limite conhecido;
- use grupos de contingência ordenados somente quando eles preservarem o modelo e o protocolo solicitados.
Criar mais chaves de API não contorna necessariamente um limite de solicitações da conta ou do grupo.
Diagnostique o 499 a partir de quem fez a chamada
O Modelflare pode registrar 499 quando a conexão com o cliente termina antes de a resposta ser concluída. Comece por quem fez a chamada:
- Um sinal de abort foi acionado?
- O cliente, o balanceador de carga, a CDN ou o proxy reverso atingiu um timeout de inatividade ou total?
- O usuário fechou a página ou interrompeu o agente?
- O stream produziu um evento de ferramenta sem texto visível?
- Quanto tempo passou até a primeira saída efetiva?
Um registro 499, por si só, não comprova uma falha do canal. Compare outras solicitações na mesma janela de tempo e com o mesmo modelo e grupo antes de alterar a política de roteamento.
Separe as falhas 5xx por camada
Em erros 5xx, preserve o status original e os detalhes do erro, em vez de converter toda falha em um 500 genérico no cliente.
- Um 500 de validação ou de adaptador pode ser determinístico e tende a falhar de novo se nada mudar.
- Um 502 pode indicar uma resposta inválida ou incompleta do provedor.
- Um 503 pode indicar que não há rota elegível ou que há indisponibilidade temporária.
- Um 504 indica que um limite de tempo expirou, mas a camada responsável ainda precisa ser identificada.
Use os tempos da solicitação, o grupo selecionado, as evidências de canal disponíveis para o suporte e as solicitações próximas para distinguir uma resposta ruim isolada de um problema persistente na rota.
Decida se vale tentar novamente
| Tipo de falha | Decisão padrão sobre nova tentativa |
|---|---|
| Payload inválido ou protocolo não suportado | Corrija a solicitação; não tente novamente sem alterações |
| Chave inválida ou acesso negado | Corrija as credenciais ou a política; não tente novamente sem alterações |
| Cota esgotada | Aumente ou redistribua a cota de forma intencional; não entre em loop |
| Limite de taxa | Tente novamente com backoff limitado, quando permitido |
| 502/503/504 temporário | Repita trabalho idempotente com um limite rígido de tentativas |
| Cancelamento pelo cliente | Tente novamente apenas se o usuário ainda quiser o resultado e duplicatas forem seguras |
| Efeito colateral de ferramenta ou de escrita | Exija idempotência no nível da aplicação antes de repetir |
Novas tentativas geram trabalho novo e podem gerar custo novo. Registre todas as tentativas e não esconda a falha original atrás de um sucesso posterior.
Evidências que podem ser coletadas com segurança
Para o suporte ou a análise de incidentes, registre:
- o ID da solicitação e o horário em UTC;
- o endpoint e o modo de streaming;
- o modelo solicitado e o grupo selecionado;
- o status HTTP e o código de erro estruturado;
- o tempo total e o tempo até a primeira saída efetiva;
- se quem fez a chamada cancelou;
- uma descrição sem dados sensíveis do recurso usado na solicitação, como ferramentas ou entrada de imagem.
Não inclua a chave de API completa, o prompt, o conteúdo da resposta, o corpo bruto da solicitação, o e-mail ou o endereço IP em texto simples, a menos que um processo seguro e aprovado exija isso especificamente.
Depois de localizar a camada com falha, use Roteamento confiável de API de IA para o design de contingência e o Guia de streaming para falhas de eventos e de timeout.
Perguntas frequentes
Um 403 prova que um provedor está fora do ar?
Não. Um 403 pode ser gerado por políticas de conta, chave, modelo, grupo, IP ou recurso antes de qualquer rota do provedor ser selecionada. Verifique primeiro o registro da solicitação e o código de erro.
O 499 é um erro padrão do modelo do provedor?
Não. Nos registros de solicitações do Modelflare, ele representa um cancelamento do lado do cliente observado antes da conclusão. Investigue os prazos de quem fez a chamada e do proxy antes de tratá-lo como falha do modelo.
Toda resposta 5xx deve ser repetida?
Não. Repita apenas operações que podem ser repetidas com segurança, use um limite de tentativas e de tempo e preserve o primeiro erro. Problemas determinísticos de adaptador ou da solicitação não vão melhorar com a repetição.