Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt

Use this file to discover all available pages before exploring further.

O tratamento de erros no CometAPI fica mais fácil quando você separa problemas no formato da requisição, problemas de autenticação, erros de path e falhas de plataforma que permitem retry. 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

StatusO que geralmente significaTentar novamente?Primeira ação
400A validação da requisição falhou antes de ela ser processada normalmente.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.
Path mistakeBase URL incorreta ou path de endpoint incorreto. No Comet, isso pode aparecer como um redirecionamento 301 ou HTML, 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 with error.code: invalid_requestUma requisição malformada apareceu por meio de uma resposta com status de servidor.NãoCorrija o corpo da requisição antes de tentar novamente.
500, 503, 504, 524Falha de plataforma, provedor ou da classe de timeout.SimTente novamente com backoff e mantenha o request id.

​
Envelope de erro

Muitas falhas do CometAPI usam um corpo de erro como este: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
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
  • Formato de JSON inválido
  • Envio de um campo com o tipo errado
  • Reutilização de parâmetros específicos do 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: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Substitua your-model-id por qualquer model ID atual da página de Models do CometAPI. Não presuma que toda requisição de chat malformada retorna 400. Campos obrigatórios ausentes no 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 do 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: 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Se uma resposta 500 tiver error.code: invalid_request, trate-a como um problema na requisição:
  1. Corrija o corpo da requisição.
  2. Compare o payload com o schema do endpoint.
  3. 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 normalmente se parece com isto: 
{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}
O que verificar:
  1. O header deve ser exatamente Authorization: Bearer <COMETAPI_KEY>.
  2. Certifique-se de que sua aplicação não está carregando uma chave antiga de .env, histórico do shell ou de um secret store implantado.
  3. 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

Na maioria das vezes, 403 é 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 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 em um model sabidamente funcional.
  2. Remova campos avançados e parâmetros específicos do provedor, 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. A correção prática continua sendo validar primeiro o token, o model e o formato da requisição.

​
URL base errada ou path errado

Na Comet, um erro de path 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: 
https://api.cometapi.com/v1
Verificações recomendadas:
  1. Confirme que a URL base inclui /v1.
  2. Confirme que o path do endpoint corresponde exatamente ao da documentação.
  3. Desative o seguimento automático de redirecionamentos ao depurar problemas de path.

​
413 Request Entity Too Large

Se você vir 413, trate isso primeiro como um problema de tamanho da requisição. Suspeitos comuns são:
  • Payloads grandes em base64
  • Imagens ou áudios grandes 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 presuma que o comprimento de texto simples seja a única causa.

​
429 Too Many Requests

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 ver qual rota e model estão saturando primeiro.
Para um padrão reutilizável de retry, consulte o exemplo de backoff em Chat Completions.

​
503, 504, and 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 provedor temporariamente indisponível
  • 504 e 524: falhas da classe de timeout entre a plataforma, a edge ou o serviço do provedor
O que fazer:
  1. Tente novamente com backoff.
  2. Guarde o request id, endpoint, model e 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
  • ID do modelo
  • JSON do corpo da requisição sanitizado (este é o item mais útil, de longe, 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 upload de arquivos (edição de imagem, upload de áudio, geração de vídeo etc.) em vez de um corpo JSON simples, envie a carga submetida equivalente:
  • 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 da requisição sanitizada exata. 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.