> ## 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. # Lidar com códigos de erro > Use este guia para classificar respostas de erro da CometAPI e aplicar etapas de nova tentativa ou correção para falhas comuns de requisição. 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 | Status | O que geralmente significa | Tentar novamente? | Primeira ação | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- | | `400` | A validação da requisição falhou antes que ela fosse processada normalmente. | Não | Valide `model`, `messages`, a estrutura 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 do endpoint incorreto. Na Comet, isso pode aparecer como um redirecionamento `301` ou HTML, não como um `404` JSON limpo. | Não | Use `https://api.cometapi.com/v1` exatamente e desative o seguimento 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` com `error.code: invalid_request` | Uma requisição malformada apareceu por meio de uma resposta com status de servidor. | Não | Corrija o corpo da requisição antes de tentar novamente. | | `500`, `503`, `504`, `524` | Falha de plataforma, provedor ou classe de timeout. | Sim | Tente novamente com backoff e mantenha o id da requisição. | ## Estrutura do erro Muitas falhas da CometAPI usam um corpo de erro como este: ```json theme={null} { "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` * 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: ```json theme={null} { "model": "your-model-id", "messages": [ { "role": "user", "content": "Hello" } ] } ``` Substitua `your-model-id` por qualquer model ID atual da [página de Models da CometAPI](/pt/overview/models). 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`: ```json theme={null} { "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 de 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 geralmente se parece com isto: ```json theme={null} { "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 seu app não está carregando uma chave antiga de `.env`, do histórico do shell ou de um armazenamento de segredos 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` `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: 1. Tente novamente com uma requisição de texto bem simples usando um model confiável. 2. Remova campos avançados e parâmetros específicos do provider, depois adicione-os novamente aos poucos. 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 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: ```text theme={null} 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 à documentação. 3. 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: 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 retry: 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 de retry reutilizável, veja o exemplo de backoff em [Chat Completions](/api/text/chat). ## `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í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 contactar 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 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. Isso reduz significativamente o tempo de resposta do suporte.