Voltar ao blog

Solução de problemasGuia

Erros comuns de conexão e como corrigi-los

O que 401, 402, 400, 404, 413, 429 e 503 significam quando você se conecta à API CheapTokens, como as respostas se parecem e como corrigir cada um.

Por CheapTokens TeamPublicado em 3 min de leitura

Lista de códigos de status HTTP 401, 402, 400, 404 e 429 com explicações curtas em um terminal
Nesta página
  1. Verificação rápida
  2. 401 — Chave de API inválida
  3. 402 — saldo vazio ou sem chave na requisição
  4. 404 — endereço errado
  5. 400 — modelo não encontrado
  6. 413 — requisição muito grande
  7. 429 — muitas requisições
  8. 503 — modelo temporariamente indisponível
  9. Esperas longas e timeouts

Quase todo problema de conexão se resume a quatro coisas: o endereço, a chave, o ID do modelo e o saldo. Comece com a verificação rápida abaixo e depois encontre seu código de status. Os corpos de resposta citados aqui são as respostas reais da API (outubro de 2026).

Verificação rápida#

bash
# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Se o primeiro comando falhar, a causa pode ser a rede do seu lado, um erro de digitação no endereço — ou o próprio serviço estar temporariamente indisponível. Se apenas o segundo falhar, procure o código de status dele abaixo. Se ambos funcionarem mas sua ferramenta não, compare as configurações da ferramenta com esses dois comandos.

401 — Chave de API inválida#

json
{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Clientes no estilo Anthropic recebem o mesmo erro em seu formato:

json
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Causas:

  • a chave foi copiada com um caractere faltando, um espaço ou aspas;
  • a chave foi rotacionada no painel — a antiga não funciona mais;
  • uma chave de outro serviço (por exemplo OpenAI) está configurada em vez da chave CheapTokens;
  • a variável de ambiente está vazia neste terminal: echo ${#CHEAPTOKENS_API_KEY} imprime seu comprimento.

O painel mostra uma chave apenas uma vez. Se ela for perdida, pressione Rotate para obter uma nova e atualize-a em todos os lugares onde é usada.

402 — saldo vazio ou sem chave na requisição#

A API retorna 402 em duas situações diferentes:

  1. O saldo acabou. As requisições são pagas com o saldo; quando ele acaba, a chave é pausada. Recarregue no painel e as requisições voltam a funcionar.
  2. A requisição não tem chave alguma. Se o cabeçalho Authorization (ou x-api-key para clientes no estilo Anthropic) estiver ausente, a API responde 402 com o tipo insufficient_funds. Verifique se sua ferramenta realmente envia a chave: o estilo OpenAI é Authorization: Bearer <key>.

404 — endereço errado#

json
{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

O caminho tem um erro de digitação — aqui completion em vez de completions. Outras causas comuns:

  • A base URL não tem /v1. Clientes no estilo OpenAI precisam de https://api.cheaptokens.dev/v1. Sem /v1 a requisição não chega à API e você recebe uma página HTML 404 simples em vez de JSON.
  • /v1 duas vezes. Alguns clientes adicionam /v1 por conta própria; então a base URL deve ser a raiz, https://api.cheaptokens.dev. Clientes no estilo Anthropic sempre usam o endereço raiz.

400 — modelo não encontrado#

json
{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

O ID do modelo deve ser o ID completo, incluindo o prefixo antes da barra: deepseek-ai/DeepSeek-V4-Flash-0731, não deepseek-v4-flash. Maiúsculas ou minúsculas não importam. A mensagem de erro lista os IDs disponíveis, e a lista completa está sempre em GET /v1/models.

Um 400 também é retornado para um corpo de requisição malformado — por exemplo um array messages vazio (messages field is required and must be a non-empty array) ou uma mensagem sem role.

413 — requisição muito grande#

O corpo da requisição é limitado a 16 MB. Agentes podem atingir esse limite colocando arquivos ou logs enormes no contexto. Envie apenas as partes que o modelo precisa e reduza saídas longas de ferramentas.

429 — muitas requisições#

Se você receber 429, diminua o ritmo. A resposta inclui um cabeçalho Retry-After com o número de segundos a esperar. Os SDKs oficiais da OpenAI tentam novamente automaticamente (max_retries); no seu próprio código, espere Retry-After antes da próxima tentativa.

503 — modelo temporariamente indisponível#

Um modelo pode ficar temporariamente indisponível; a API então responde 503 com o tipo model_unavailable, e o card do modelo no site mostra "temporariamente indisponível". Tente novamente mais tarde ou mude o campo model para outro modelo — a chave e o endereço permanecem os mesmos.

Esperas longas e timeouts#

Modelos de raciocínio como zai-org/GLM-5.3-Flash pensam antes de responder, então o primeiro token pode demorar. Use streaming ou aumente o timeout do cliente — por exemplo timeout=120 no SDK da OpenAI.

Tags: