Erros da API BetterToken: códigos HTTP e limites

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. Se ainda não concluiu uma solicitação a um modelo, comece pelos exemplos de SDK ou pelo guia de configuração da sua ferramenta.

Leia a resposta de erro

O BetterToken retorna erros da API em uma estrutura JSON. Por exemplo, uma solicitação sem Key pode retornar:

{
  "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	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. Para dúvidas sobre cache, consulte as perguntas sobre cobrança de cache.

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 e substitua os dois valores de exemplo. Use um modelo de texto disponível em Chat Completions.

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
JavaScript

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)

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
Codex pede login ou ignora mudanças de provedor	Erros comuns do Codex CLI / App
Não é possível ativar a Key do Cursor ou os modelos integrados param de funcionar	Erros comuns do Cursor
Erro de autenticação, `404` ou modelo no Cline	Erros comuns do Cline
Erro de provedor, modelo ou configuração de projeto no OpenCode	Erros comuns do OpenCode
O Gateway do Claude Desktop não conecta	Erros comuns do Claude Desktop
Aviso de uso do Codex oficial ou `429` da API	Limite de uso e limite de requisições da API
As alterações parecem não ter efeito	Remover variáveis de ambiente conflitantes
Saída truncada ou erro de limite de saída	Limites de tokens de saída

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 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 e verifique com uma solicitação pequena.

Referência da API

Guias para desenvolvedores

Erros da API BetterToken: códigos HTTP e limites

Antes de investigar o problema

Leia a resposta de erro

Verifique o status HTTP

Repita falhas temporárias

Prepare a solicitação

Encontre o guia para o seu caso

Confirme a correção

Perguntas frequentes

Todo erro 429 exige esperar e tentar novamente?

Devo aumentar o tempo limite após uma falha?

Conteúdo relacionado

​Antes de investigar o problema

​Leia a resposta de erro

​Verifique o status HTTP

​Repita falhas temporárias

​Prepare a solicitação

​Encontre o guia para o seu caso

​Confirme a correção

​Perguntas frequentes

​Todo erro 429 exige esperar e tentar novamente?

​Devo aumentar o tempo limite após uma falha?

​Conteúdo relacionado

Antes de investigar o problema

Leia a resposta de erro

Verifique o status HTTP

Repita falhas temporárias

Prepare a solicitação

Encontre o guia para o seu caso

Confirme a correção

Perguntas frequentes

Todo erro 429 exige esperar e tentar novamente?

Devo aumentar o tempo limite após uma falha?

Conteúdo relacionado