Erro "tokens insuficientes": o que significa e como corrigir

"Tokens insuficientes" não é um único erro. As pessoas usam a frase para cinco problemas diferentes: o saldo está vazio, as requisições estão chegando rápido demais, a chave está errada, o prompt não cabe na janela de contexto do modelo, ou a resposta atingiu o limite de saída e parou no meio da frase. Cada um tem sua própria correção, e a forma mais rápida de distingui-los é o status HTTP e o corpo do erro, não o texto da mensagem.

Encontre seu sintoma na tabela, execute a verificação, aplique a correção.

Três coisas que "tokens" pode significar#

A palavra na mensagem de erro aponta para três quantidades diferentes.

• Saldo. Tokens são o que você paga, então "sem tokens" muitas vezes significa "sem dinheiro". Em um serviço pré-pago, isso é o saldo.
• Um limite por minuto. Limites podem ser contados em requisições ou em tokens por minuto. Atingiu um, a correção é esperar e enviar menos de uma vez.
• Tamanho da janela. A janela de contexto é quantos tokens o modelo consegue ler em uma requisição, seu prompt e a resposta juntos.

E uma coisa que nunca significa: uma chave de API não é um estoque de tokens. A chave identifica sua conta. O que acaba é o saldo por trás dela, ou um limite atrelado a ela. Se você é novo na unidade em si, comece por O que é um token em IA?.

1. O saldo está vazio#

A documentação da API do DeepSeek descreve o HTTP 402 Insufficient Balance como "Você ficou sem saldo". A API do Claude usa 402 billing_error para problemas de cobrança e pagamento. Nomes diferentes, mesma situação: o dinheiro acabou.

O CheapTokens funciona da mesma forma em princípio: saldo pré-pago, pague conforme o uso, um saldo para todos os modelos. Então, quando algo quebra, olhe o saldo primeiro. É uma verificação de dez segundos e elimina a causa mais comum.

2. Você atingiu um limite de taxa#

O DeepSeek documenta o HTTP 429 Rate Limit Reached como requisições chegando rápido demais, ou um limite de concorrência ou QPS sendo excedido. A correção é dosá-las: menos requisições paralelas, e um atraso de nova tentativa que cresce (1 s, 2 s, 4 s) em vez de martelar o endpoint.

Uma armadilha. A API do Claude também retorna 429 rate_limit_error quando você atinge o teto de gasto mensal do seu nível, e essa resposta não tem cabeçalho retry-after. Então um 429 que nunca passa depois de esperar pode ser sobre dinheiro, não velocidade. Se esperar não ajudar, volte à causa 1.

3. A chave está errada#

HTTP 401 é um problema de chave em ambas as documentações: o DeepSeek lista como chave de API errada, o Claude como authentication_error. Os motivos usuais são um espaço ou quebra de linha extra copiado junto com a chave, uma chave que foi excluída ou regenerada, e uma chave enviada para o endereço errado. Uma chave de um serviço não funciona na URL de outro serviço. Para o CheapTokens a URL base é https://api.cheaptokens.dev/v1.

Para os outros erros que você pode encontrar ao conectar, veja Erros de conexão comuns e como corrigi-los.

4. O prompt não cabe na janela de contexto#

A janela de contexto conta tudo que o modelo lê em uma requisição: o prompt de sistema, todo o histórico da conversa, sua nova mensagem, e espaço para a resposta. No CheapTokens, as janelas dos modelos do nosso catálogo são:

Um chat não tem memória própria. O cliente envia todo o histórico novamente a cada requisição, então cada requisição é maior que a anterior. Aqui está um chat fictício para mostrar o crescimento (números redondos, para ilustração): um prompt de sistema de 1.000 tokens, e cada turno adiciona cerca de 500 tokens de pergunta e 1.500 tokens de resposta, 2.000 no total.

1.000 + 30 × 2.000 = 61.000 tokens

Esse é o tamanho do histórico após 30 turnos. Cada um desses tokens conta como entrada novamente na próxima requisição. A 31ª requisição carrega esse histórico de 61.000 tokens mais a nova pergunta de 500 tokens, então sua entrada é de 61.500 tokens. Com uma resposta de 1.500 tokens no MiniMax-M2.7 custa $0.0033. Aqui estão os três modelos para a mesma requisição, com o preço do OpenRouter para comparação:

O mesmo chat preenche a menor janela em cerca de cem turnos:

(200.000 − 1.000) / 2.000 = 99,5

Quando transborda, o provedor rejeita a requisição. O código de status varia por provedor, então leia o corpo do erro. O 413 request_too_large do Claude, por exemplo, é sobre o tamanho da requisição em bytes (32 MB para Messages), um limite diferente da janela de tokens.

O que fazer:

• Descarte os turnos mais antigos, ou substitua-os por um resumo curto.
• Não cole um documento inteiro quando a tarefa precisa de um capítulo.
• Mude para um modelo com janela maior se você realmente precisa do texto completo.

5. A resposta foi cortada#

Nenhum erro aqui, e é isso que torna este confuso. O modelo simplesmente parou porque atingiu max_tokens ou o próprio limite de saída do modelo. No formato Chat Completions o sinal é finish_reason: "length" na escolha.

No CheapTokens, o DeepSeek-V4-Flash pode retornar até 32.768 tokens por resposta; GLM-5.3-Flash e MiniMax-M2.7 até 8.192. Se seu max_tokens for menor que isso, aumente. Se você já está no limite, divida o trabalho ("escreva a parte 1 de 3") ou peça ao modelo para continuar a partir da última frase.

A saída do MiniMax-M2.7 custa $0.15 por 1M tokens, e isso é mais barato que o OpenRouter na saída.

O mesmo problema com nomes diferentes#

Os provedores rotulam as mesmas causas de forma diferente. Isto é o que suas documentações dizem em 20 de outubro de 2026:

Fontes: códigos de erro do DeepSeek, erros da API do Claude. Nenhuma das páginas mostra data de publicação, então a data de verificação é nossa.

A conclusão: não adivinhe pelo texto. Erros voltam como JSON com um objeto error contendo um type e um message. Compare pelo status e pelo tipo, porque o texto da mensagem muda.

Veja o que realmente volta#

Este trecho imprime o status e o corpo de uma requisição falha e o finish_reason de uma bem-sucedida. É um esboço de diagnóstico, não um log de teste: execute com sua própria chave e leia o que receber.

# Placeholders: YOUR_API_KEY, MODEL_ID (a model id you have access to)
from openai import OpenAI, APIStatusError

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.cheaptokens.dev/v1")

try:
    r = client.chat.completions.create(
        model="MODEL_ID",
        messages=[{"role": "user", "content": "Write a long checklist."}],
        max_tokens=1000,
    )
except APIStatusError as e:
    # Read the status and the body, not the wording of the message
    print("status:", e.status_code)
    print("body:", e.body)
else:
    print("finish_reason:", r.choices[0].finish_reason)  # "length" = cut off
    print("usage:", r.usage)  # prompt_tokens and completion_tokens

Se a verificação apontar para o saldo#

Recarregue o saldo e envie a requisição novamente. Os preços no CheapTokens são fixos por modelo, não há horários de pico, e um saldo cobre todos os modelos, então você não precisa de uma recarga separada para cada um. As tarifas atuais estão aqui:

Coloque seu próprio volume na tabela de custos antes de recarregar. Recarregue seu saldo quando os números fizerem sentido, e se quiser estimar uma carga de trabalho maior primeiro, veja Como estimar o custo de um agente de IA.