Códigos de Erro e Tratamento

Solucione falhas de requisição do CometAPI com orientações verificadas para erros 400, 401 e de caminho, além de tratamento prático para falhas 403, 429 e da classe timeout.

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

Status	O que normalmente significa	Retry?	Primeira ação
400	A validação da requisição falhou antes de ela ser roteada com sucesso.	Não	Valide model, messages, o formato do JSON e os tipos dos campos.
401	A chave de API está ausente, malformada ou inválida.	Não	Verifique Authorization: Bearer <COMETAPI_KEY>.
403	O acesso foi bloqueado ou a requisição atual não foi permitida.	Geralmente não	Tente novamente com uma requisição sabidamente válida e remova primeiro os campos específicos do model.
Erro de caminho	Base 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ão	Use https://api.cometapi.com/v1 exatamente e desative o acompanhamento automático de redirecionamentos durante a depuração.
429	Limitação de taxa ou saturação temporária.	Sim	Use exponential backoff com jitter.
500, 503, 504, 524	Falha de plataforma ou da classe timeout.	Sim	Tente 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.