O tratamento de erros da CometAPI fica mais fácil quando você separa problemas de estrutura da requisição, problemas de autenticação, erros de caminho, e falhas de plataforma que permitem nova tentativa. Use a combinação de status HTTP, error.code e error.message para decidir se deve corrigir a requisição ou tentar novamente.
Triagem rápida
Estrutura do erro
Muitas falhas da CometAPI usam um corpo de erro como este:
Algumas respostas deixam code vazio. Quando o status é 500, trate error.code e error.message como o sinal decisivo.
400 Bad Request
Um 400 geralmente significa que o corpo da requisição falhou na validação antes que a requisição pudesse ser processada normalmente.
Causas comuns:
- Campos obrigatórios ausentes, como
model
- Estrutura de JSON inválida
- Envio de um campo com o tipo errado
- Reutilização de parâmetros específicos de provedor que o endpoint selecionado não aceita
Comece com uma requisição mínima sabidamente válida e, em seguida, adicione os campos opcionais de volta um por um. Compare o payload com o schema do endpoint na referência da API.
Use uma requisição mínima como esta:
Substitua your-model-id por qualquer model ID atual da página de Models da CometAPI.
Não presuma que toda requisição de chat malformada retorna 400. Campos obrigatórios ausentes em chat, como messages, também podem aparecer como 500 com error.code: invalid_request.
500 Internal Server Error
A maioria das respostas 500 indica uma falha de plataforma ou de provedor. Para Chat Completions, algumas requisições malformadas também podem aparecer como 500 enquanto ainda carregam error.code: invalid_request.
Um exemplo é uma requisição que omite messages:
Se uma resposta 500 tiver error.code: invalid_request, trate-a como um problema de requisição:
- Corrija o corpo da requisição.
- Compare o payload com o schema do endpoint.
- Tente novamente somente após corrigir o payload.
Se uma resposta 500 não apontar para uma requisição inválida, mantenha o request id e use backoff.
401 Invalid Token
Uma falha de token geralmente se parece com isto:
O que verificar:
- O header deve ser exatamente
Authorization: Bearer $COMETAPI_KEY.
- Certifique-se de que seu app não está carregando uma chave antiga de
.env, do histórico do shell ou de um armazenamento de segredos implantado.
- Se uma chave falha e outra funciona na mesma requisição, trate isso como um problema de token, não como um problema de endpoint.
403 Forbidden
403 geralmente é uma destas situações:
- A requisição é bloqueada por uma regra do lado da plataforma, como filtragem WAF
- O token ou a rota não têm permissão para usar o model solicitado ou o formato de requisição solicitado
- O model escolhido rejeita um dos parâmetros avançados que você passou
O que fazer primeiro:
- Tente novamente com uma requisição de texto bem simples usando um model confiável.
- Remova campos avançados e parâmetros específicos do provider, depois adicione-os novamente aos poucos.
- Se a resposta incluir um request id, guarde-o antes de entrar em contato com o suporte.
Se a mensagem mencionar termos internos como group ou channel, trate-os como detalhes de roteamento, não como a primeira coisa a diagnosticar do lado do cliente. Na prática, a correção continua sendo validar primeiro o token, o model e o formato da requisição.
URL base errada ou caminho errado
Na Comet, um erro no caminho pode aparecer como:
- Um redirecionamento
- Uma resposta HTML não JSON se seu cliente seguir redirecionamentos
- Um erro de parsing dentro do seu SDK
- Uma requisição que nunca chega de forma limpa à camada da API
Use esta URL base exatamente:
Verificações recomendadas:
- Confirme que a URL base inclui
/v1.
- Confirme que o caminho do endpoint corresponde exatamente à documentação.
- Desative o seguimento automático de redirecionamentos ao depurar problemas de caminho.
413 Request Entity Too Large
Se você vir 413, trate-o primeiro como um problema de tamanho da requisição. Suspeitos comuns são:
- Payloads base64 grandes
- Imagens ou áudio muito grandes embutidos inline
- Corpos multipart ou JSON muito grandes
O que fazer:
- Reduza ou comprima o conteúdo anexado.
- Divida trabalhos grandes em requisições menores.
- Não presuma que o comprimento de texto simples seja a única causa.
429 Too Many Requests
Trate 429 como passível de retry:
- Use exponential backoff com jitter.
- Reduza a concorrência em rajada.
- Mantenha o logging de requisições ativado para ver qual rota e model estão saturando primeiro.
Para um padrão de retry reutilizável, veja o exemplo de backoff em Chat Completions.
503, 504 e 524
Esses status são falhas do lado do servidor ou da classe de timeout.
Orientação prática:
503: rota ou serviço do provider temporariamente indisponível504 e 524: falhas da classe de timeout entre a plataforma, a edge ou o serviço do provider
O que fazer:
- Tente novamente com backoff.
- Guarde o
request id, o endpoint, o model e o timestamp.
- Se a mesma falha se repetir em várias tentativas, entre em contato com o suporte com esse contexto.
Capture estes detalhes primeiro:
- Método HTTP
- Caminho do endpoint
- ID do modelo
- JSON do corpo da requisição sanitizado (este é o item mais útil para a maioria das chamadas de API)
- Parâmetros de query, se a requisição com falha os utilizou
- Corpo da resposta exato, se o seu cliente o capturou
- Status HTTP completo
- O
error.message exato
- Qualquer
request id
- Timestamp aproximado
- Se a mesma requisição funciona com outro modelo ou outro token
Se a rota com falha aceitar uploads de arquivo (edição de imagem, upload de áudio, geração de vídeo, etc.) em vez de um corpo JSON simples, envie a carga útil equivalente submetida:
- Nomes dos campos e valores de texto que você enviou junto com o arquivo
- Nome do arquivo, tipo do arquivo e tamanho aproximado do arquivo
- Se o arquivo foi enviado diretamente, referenciado por URL ou incorporado como base64
A forma mais eficaz de reproduzir um bug é a carga útil exata da requisição sanitizada. Para a maioria das chamadas de API, isso significa o JSON bruto do corpo da requisição. Para rotas de upload de arquivo, isso significa a lista de campos mais os metadados do arquivo.
