> ## Documentation Index > Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt > Use this file to discover all available pages before exploring further. # Erros da API BetterToken: códigos HTTP e limites > Diagnostique erros da API BetterToken pelo status HTTP, corpo da resposta e ID da solicitação. Resolva falhas de autenticação, limites e tempos limite. Diagnostique um erro da API BetterToken combinando o status HTTP e o corpo da resposta. Registre o ID da solicitação em `error.message`, corrija erros de autenticação ou configuração antes de reenviar e repita apenas falhas identificadas como temporárias. ## Antes de investigar o problema Tenha em mãos o Model ID, a Base URL e a resposta com erro. Verifique o status da Key e o saldo atual no [Dashboard do BetterToken](https://bettertoken.ai/workspace). Se ainda não concluiu uma solicitação a um modelo, comece pelos [exemplos de SDK](/pt-br/guides/sdk-examples.md) ou pelo [guia de configuração da sua ferramenta](/pt-br/ai-tools/overview.md). ## Leia a resposta de erro O BetterToken retorna erros da API em uma estrutura JSON. Por exemplo, uma solicitação sem Key pode retornar: ```json theme={null} { "error": { "code": "", "message": "Token not provided (request id: …)", "type": "new_api_error" } } ``` Leia `error.message` mesmo quando `error.code` estiver vazio. O ID da solicitação nessa mensagem ajuda a identificar a tentativa que falhou. Uma solicitação a `/v1/models` sem Key retorna `401`; ela não testa se o modelo consegue gerar uma resposta. Registre estes dados antes de entrar em contato com o suporte: | Dado | O que registrar | | - | - | | Status HTTP | Status da resposta ou exceção de rede ou tempo limite do cliente, caso não tenha recebido resposta HTTP | | Corpo da resposta | JSON de erro ou outro conteúdo retornado, sem segredos | | ID da solicitação | Identificador em `error.message`, quando presente | | Horário | Data, hora e fuso horário da tentativa | | Model ID | Valor exato enviado como `model` | | Base URL | Base URL configurada e caminho final da solicitação | Não inclua sua BetterToken API Key em capturas de tela, mensagens de suporte ou registros compartilhados. ## Verifique o status HTTP A tabela usa os significados gerais de HTTP e APIs e as orientações de configuração vinculadas. Ela não lista códigos específicos do BetterToken; leia a resposta real antes de escolher uma correção. | Status | Significado comum | O que verificar primeiro | Tentar novamente? | | - | - | - | - | | `400` | Solicitação, campo ou combinação de parâmetros inválidos | Estrutura JSON, campos obrigatórios, modelo e especificação do endpoint | Corrija a solicitação primeiro | | `401` | Credencial ausente, inválida, expirada ou revogada | Status da Key, espaços em branco e cabeçalho de autenticação do protocolo | Corrija a autenticação primeiro | | `403` | Solicitação recusada | Mensagem da resposta, saldo, status da Key e configuração do cliente | Resolva a recusa primeiro | | `404` | Rota ou recurso solicitado não encontrado | Base URL, `/v1` duplicado ou ausente, caminho final e Model ID exato | Corrija a URL ou o recurso primeiro | | `408` / tempo limite do cliente | O servidor não recebeu a solicitação completa a tempo ou o cliente parou de esperar | Se houve status HTTP, configurações de tempo limite, rede e status da solicitação no Dashboard | Verifique se a solicitação terminou antes de decidir | | `409` / `422`, se retornados | Em geral, conflito ou conteúdo que não pode ser processado | Detalhes da resposta e estado ou campos enviados | Resolva a causa primeiro | | `429` | Um limite foi atingido | Corpo da resposta e cabeçalhos de nova tentativa; consulte as [perguntas sobre diagnóstico de limites](/pt-br/faq/codex/usage-limit-vs-api-rate-limit.md) | Apenas se identificado como limite temporário de requisições | | `500` | Falha no servidor | Registro da solicitação, mensagem e persistência da falha | Novas tentativas limitadas para falha temporária | | `502` / `503` | Falha no gateway ou serviço de origem, ou indisponibilidade temporária | Corpo da resposta e cabeçalho `Retry-After`, quando presente | Novas tentativas limitadas para falha temporária | | `504` | O gateway excedeu o tempo de espera pela resposta do serviço de origem | Registro no Dashboard e se a solicitação terminou | Verifique a conclusão antes de repetir | Para erros de protocolo ou sufixo, consulte as [perguntas sobre Base URL](/pt-br/faq/model-calling/base-url-config.md). Para dúvidas sobre cache, consulte as [perguntas sobre cobrança de cache](/pt-br/faq/service-assurance/cache-billing.md). ## Repita falhas temporárias Após identificar um `429` temporário ou uma falha temporária do servidor, use espera exponencial com variação aleatória e limites. Respeite `Retry-After` quando retornado; se exceder seu limite de espera, interrompa o laço e aguarde fora dele. As novas tentativas do SDK e do seu laço compartilham o mesmo total de tentativas; desative as do SDK ao implementar sua própria política. Não repita sem alterações erros `400`, `401`, `403`, de saldo ou de configuração. Um tempo limite excedido ou um streaming interrompido não prova que a solicitação falhou antes de ser processada. Confira primeiro o **Dashboard**, principalmente em geração de imagens ou fluxos que possam repetir uma ação. Os exemplos abaixo enviam uma solicitação a Chat Completions sem streaming, com no máximo quatro tentativas. Eles repetem os status HTTP `500`, `502` e `503`. As novas tentativas de `429` ficam desativadas até você confirmar um limite temporário; os exemplos param em tempos limite, exceções de rede e `504` para você verificar a conclusão. A espera máxima por nova tentativa é de 30 segundos. ### Prepare a solicitação Copie um Model ID atual da [model plaza](https://bettertoken.ai/pricing) e substitua os dois valores de exemplo. Use um modelo de texto disponível em [Chat Completions](/pt-br/api-reference/chat-completions.md). ```bash theme={null} export BETTERTOKEN_API_KEY="YOUR_API_KEY" export BETTERTOKEN_MODEL_ID="YOUR_MODEL_ID" ``` O exemplo Python usa a biblioteca padrão. Salve o exemplo JavaScript em um arquivo `.mjs` e execute-o com uma versão do Node.js que ofereça `fetch` e `AbortSignal.timeout`. **Python** ```python theme={null} import json import os import random import time import urllib.error import urllib.request from datetime import datetime, timezone from email.utils import parsedate_to_datetime def retry_after_seconds(value): try: return max(0.0, float(value)) except ValueError: return max(0.0, ( parsedate_to_datetime(value) - datetime.now(timezone.utc) ).total_seconds()) retry_temporary_429 = False # Enable only after diagnosing the returned limit. payload = json.dumps({ "model": os.environ["BETTERTOKEN_MODEL_ID"], "messages": [{"role": "user", "content": "Reply with one word: OK"}], }).encode() for attempt in range(4): request = urllib.request.Request( "https://bettertoken.ai/v1/chat/completions", data=payload, headers={ "Authorization": "Bearer " + os.environ["BETTERTOKEN_API_KEY"], "Content-Type": "application/json", }, ) try: with urllib.request.urlopen(request, timeout=120) as response: print(json.load(response)["choices"][0]["message"]["content"]) break except urllib.error.HTTPError as error: body = error.read().decode("utf-8", errors="replace") retryable = error.code in (500, 502, 503) or ( error.code == 429 and retry_temporary_429 ) if not retryable or attempt == 3: raise RuntimeError(f"HTTP {error.code}: {body}") from error delay = random.uniform(0, min(8.0, 2.0 ** attempt)) retry_after = error.headers.get("Retry-After") if retry_after: delay = max(delay, retry_after_seconds(retry_after)) if delay > 30: raise RuntimeError("Retry-After exceeds this retry budget") from error time.sleep(delay) ``` **JavaScript** ```javascript theme={null} const retryTemporary429 = false; // Enable only after diagnosing the returned limit. const payload = { model: process.env.BETTERTOKEN_MODEL_ID, messages: [{ role: "user", content: "Reply with one word: OK" }], }; for (let attempt = 0; attempt < 4; attempt++) { const response = await fetch("https://bettertoken.ai/v1/chat/completions", { method: "POST", headers: { Authorization: `Bearer ${process.env.BETTERTOKEN_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(payload), signal: AbortSignal.timeout(120000), }); const body = await response.text(); if (response.ok) { console.log(JSON.parse(body).choices[0].message.content); break; } const retryable = [500, 502, 503].includes(response.status) || (response.status === 429 && retryTemporary429); if (!retryable || attempt === 3) { throw new Error(`HTTP ${response.status}: ${body}`); } let delay = Math.random() * Math.min(8000, 1000 * 2 ** attempt); const retryAfter = response.headers.get("Retry-After"); if (retryAfter !== null) { const seconds = Number(retryAfter); const wait = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(retryAfter) - Date.now(); if (!Number.isFinite(wait)) throw new Error("Invalid Retry-After header"); delay = Math.max(delay, wait, 0); } if (delay > 30000) throw new Error("Retry-After exceeds this retry budget"); await new Promise(resolve => setTimeout(resolve, delay)); } ``` Se o corpo da resposta indicar um problema persistente de configuração, saldo ou acesso, interrompa o laço e corrija o problema, mesmo que o status isolado pareça permitir novas tentativas. Antes de usar este exemplo curto de texto em outras operações, adapte-o às verificações de conclusão da aplicação. ## Encontre o guia para o seu caso | Sintoma | Guia | | - | - | | Erro de autenticação, URL ou modelo no Claude Code | [Erros comuns do Claude Code](/pt-br/ai-tools/claude-code.md#common-errors) | | Codex pede login ou ignora mudanças de provedor | [Erros comuns do Codex CLI / App](/pt-br/ai-tools/codex.md#common-errors) | | Não é possível ativar a Key do Cursor ou os modelos integrados param de funcionar | [Erros comuns do Cursor](/pt-br/ai-tools/cursor.md#common-errors) | | Erro de autenticação, `404` ou modelo no Cline | [Erros comuns do Cline](/pt-br/ai-tools/cline.md#common-errors) | | Erro de provedor, modelo ou configuração de projeto no OpenCode | [Erros comuns do OpenCode](/pt-br/ai-tools/opencode.md#common-errors) | | O Gateway do Claude Desktop não conecta | [Erros comuns do Claude Desktop](/pt-br/faq/claude-desktop-bettertoken-api.md#common-errors) | | Aviso de uso do Codex oficial ou `429` da API | [Limite de uso e limite de requisições da API](/pt-br/faq/codex/usage-limit-vs-api-rate-limit.md) | | As alterações parecem não ter efeito | [Remover variáveis de ambiente conflitantes](/pt-br/best-practices.md#clear-conflicting-environment-variables) | | Saída truncada ou erro de limite de saída | [Limites de tokens de saída](/pt-br/faq/model-calling/max-tokens.md) | ## Confirme a correção Envie uma solicitação curta e não crítica com o mesmo cliente, Base URL e Model ID que falharam. Confirme uma resposta normal e encontre o registro correspondente no **Dashboard**. Confira modelo, status, uso de tokens e cobrança antes de retomar um fluxo maior. ## Perguntas frequentes ### Todo erro 429 exige esperar e tentar novamente? Use as [perguntas sobre diagnóstico de limites de uso](/pt-br/faq/codex/usage-limit-vs-api-rate-limit.md) para decidir o que verificar e se uma nova tentativa se aplica à sua resposta. ### Devo aumentar o tempo limite após uma falha? Primeiro, identifique se o cliente, um proxy ou uma solicitação ao serviço de origem parou de esperar. Consulte as [orientações de tempo limite](/pt-br/best-practices.md#set-a-generous-timeout) e verifique com uma solicitação pequena. ## Conteúdo relacionado * [Exemplos de solicitações com SDK](/pt-br/guides/sdk-examples.md) * [Streaming e chamadas de ferramentas](/pt-br/guides/streaming-and-tool-calling.md) * [Referência da API](/pt-br/api-reference/introduction.md) * [Ferramentas compatíveis](/pt-br/ai-tools/overview.md) * [Perguntas sobre cobrança de cache](/pt-br/faq/service-assurance/cache-billing.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.