Saltar para o conteúdo principal
O tratamento de erros no CometAPI fica mais fácil quando você separa problemas de requisição, problemas de autenticação e problemas de plataforma passíveis de retry. Esta página é o guia canônico de erros do CometAPI e se concentra no que você pode verificar primeiro do lado do cliente.
Este guia se baseia em verificações reais na API atual do CometAPI. Verificamos diretamente falhas de 400, 401 e de caminho/base URL. Não reproduzimos 413, 429, 500, 503, 504 ou 524 em testes limitados, portanto a orientação para esses status é intencionalmente conservadora.

​
Triagem Rápida

StatusO que normalmente significaRetry?Primeira ação
400A validação da requisição falhou antes de ela ser roteada com sucesso.NãoValide model, messages, o formato do JSON e os tipos dos campos.
401A chave de API está ausente, malformada ou inválida.NãoVerifique Authorization: Bearer <COMETAPI_KEY>.
403O acesso foi bloqueado ou a requisição atual não foi permitida.Geralmente nãoTente novamente com uma requisição sabidamente válida e remova primeiro os campos específicos do model.
Erro de caminhoBase URL incorreta ou caminho de endpoint incorreto. No Comet, isso pode aparecer como um redirecionamento 301 ou HTML, e não como um 404 JSON limpo.NãoUse https://api.cometapi.com/v1 exatamente e desative o acompanhamento automático de redirecionamentos durante a depuração.
429Limitação de taxa ou saturação temporária.SimUse exponential backoff com jitter.
500, 503, 504, 524Falha de plataforma ou da classe timeout.SimTente novamente com backoff e mantenha o request id.

​
Envelope de Erro

O envelope de erro JSON atual retornado pelo CometAPI se parece com isto: 
{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}
Muitas mensagens de erro reais também incluem um request id dentro de error.message. Salve esse valor quando precisar de suporte.

​
400 Bad Request

O que observamos na API real quando model foi omitido: 
{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}
Na prática, 400 normalmente significa que o corpo da requisição falhou na validação antes que a plataforma pudesse roteá-la para o provedor de model. Causas comuns:
  • Campos obrigatórios ausentes, como model ou messages
  • Formato JSON inválido
  • Envio de um campo com o tipo errado
  • Reutilização de parâmetros específicos de provedor que o endpoint selecionado não aceita
O que fazer:
  1. Comece com uma requisição mínima sabidamente válida.
  2. Adicione os campos opcionais de volta um por um.
  3. Compare o corpo da requisição com o schema do endpoint na referência da API.
Exemplo mínimo sabidamente válido: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Substitua your-model-id por qualquer ID de model atual da página de Models do CometAPI.

​
401 Invalid Token

O que observamos na API real com uma chave inválida: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
O que verificar:
  1. O cabeçalho deve ser exatamente Authorization: Bearer <COMETAPI_KEY>.
  2. Certifique-se de que seu app não esteja carregando uma chave antiga de .env, do histórico do shell ou de um armazenamento de secrets implantado.
  3. Se uma chave falhar e outra funcionar na mesma requisição, trate isso como um problema de token, não de endpoint.

​
403 Forbidden

Não reproduzimos um 403 estável em testes limitados, portanto evite tratar um único modelo antigo de mensagem como se explicasse toda a situação. Na documentação atual do Comet, 403 é mais frequentemente discutido como uma destas situações:
  • A requisição é bloqueada por uma regra do lado da plataforma, como filtragem por WAF
  • O token ou a rota não têm permissão para usar o model solicitado ou o formato da requisição
  • O model escolhido rejeita um dos parâmetros avançados que você enviou
O que fazer primeiro:
  1. Tente novamente com uma requisição de texto bem simples contra um model sabidamente funcional.
  2. Remova campos avançados e parâmetros específicos do provider, depois adicione-os de volta gradualmente.
  3. 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

Esta é a área em que a página antiga estava menos precisa. Em verificações ao vivo contra os endpoints atuais do Comet:
  • Enviar uma requisição para https://api.cometapi.com/chat/completions retornou um redirecionamento 301 para https://www.cometapi.com/chat/completions
  • Enviar uma requisição para uma rota de API falsa, como https://api.cometapi.com/v1/not-a-real-endpoint, também retornou um redirecionamento 301 para https://www.cometapi.com/v1/not-a-real-endpoint
Isso significa que um erro no caminho pode aparecer como:
  • Um redirecionamento
  • Uma resposta HTML não JSON se o 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: 
https://api.cometapi.com/v1
Verificações recomendadas:
  1. Confirme que a URL base inclui /v1.
  2. Confirme que o caminho do endpoint corresponde exatamente ao da documentação.
  3. Desative o seguimento automático de redirecionamentos ao depurar problemas de caminho.

​
413 Request Entity Too Large

Não reproduzimos 413 em um teste limitado, mesmo com um corpo de requisição JSON superdimensionado de 8 MiB, portanto a explicação antiga de que o prompt era longo demais era restrita demais. Se você realmente encontrar 413, trate primeiro como um problema de tamanho da requisição. Suspeitos comuns são:
  • Payloads base64 grandes
  • Imagens ou áudio superdimensionados incorporados inline
  • Corpos multipart ou JSON muito grandes
O que fazer:
  1. Reduza ou comprima o conteúdo anexado.
  2. Divida trabalhos grandes em requisições menores.
  3. Não suponha que o tamanho do texto simples seja a única causa.

​
429 Too Many Requests

Não reproduzimos 429 durante uma sondagem limitada de concorrência com 24 requisições paralelas GET /v1/models, então o limite exato claramente depende da rota, do model e do estado atual da plataforma. Trate 429 como passível de nova tentativa:
  1. Use exponential backoff com jitter.
  2. Reduza a concorrência em rajada.
  3. Mantenha o logging de requisições ativado para que você possa ver qual rota e model estão saturando primeiro.
Para um padrão reutilizável de retry, veja o exemplo de backoff em Chat Completions.

​
500, 503, 504, E 524

Não reproduzimos esses status em testes limitados. Eles devem ser documentados como falhas do lado do servidor ou da classe de timeout, não como erros do usuário. Orientação prática:
  • 500: falha interna da plataforma ou do lado do provider
  • 503: rota ou serviço do provider temporariamente indisponível
  • 504 e 524: falhas da classe de timeout entre a plataforma, a edge ou o serviço do provider
O que fazer:
  1. Tente novamente com backoff.
  2. Guarde o request id, o endpoint, o model e o timestamp.
  3. Se a mesma falha se repetir em várias tentativas, entre em contato com o suporte com esse contexto.

​
Antes de Entrar em Contato com o Suporte

Capture estes detalhes primeiro:
  • Método HTTP
  • Caminho do endpoint
  • Nome do model
  • 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 model ou outro token
Se a rota com falha aceitar uploads de arquivos (edição de imagem, upload de áudio, geração de vídeo etc.) em vez de um corpo JSON simples, envie o payload submetido equivalente:
  • Nomes dos campos e valores de texto que você enviou junto com o arquivo
  • Nome do arquivo, tipo de arquivo e tamanho aproximado do arquivo
  • Se o arquivo foi enviado diretamente, referenciado por URL ou incorporado como base64
A forma mais rápida de reproduzir um bug é ter o payload exato 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 arquivos, isso significa a lista de campos mais os metadados do arquivo.
Isso reduz significativamente o tempo de resposta do suporte.