Error "Not enough tokens": qué significa y cómo solucionarlo

"Not enough tokens" no es un único error. La gente usa la frase para cinco problemas distintos: el saldo está vacío, las solicitudes llegan demasiado rápido, la clave es incorrecta, el prompt no cabe en la ventana de contexto del modelo, o la respuesta alcanzó el límite de salida y se cortó a mitad de frase. Cada uno tiene su propia solución, y la forma más rápida de distinguirlos es el estado HTTP y el cuerpo del error, no el texto del mensaje.

Encuentra tu síntoma en la tabla, ejecuta la comprobación, aplica la solución.

Tres cosas que puede significar "tokens"#

La palabra en el mensaje de error apunta a tres cantidades distintas.

• Saldo. Los tokens son lo que pagas, así que "sin tokens" a menudo significa "sin dinero". En un servicio de prepago esto es el saldo.
• Un límite por minuto. Los límites pueden contarse en solicitudes o en tokens por minuto. Si alcanzas uno, la solución es esperar y enviar menos a la vez.
• Tamaño de la ventana. La ventana de contexto es cuántos tokens puede leer el modelo en una solicitud, tu prompt y su respuesta juntos.

Y una cosa que nunca significa: una clave de API no es una reserva de tokens. La clave identifica tu cuenta. Lo que se agota es el saldo detrás de ella, o un límite asociado a ella. Si eres nuevo en la unidad en sí, empieza por ¿Qué es un token en IA?.

1. El saldo está vacío#

La documentación de la API de DeepSeek describe el HTTP 402 Insufficient Balance como "Te has quedado sin saldo". La API de Claude usa 402 billing_error para problemas de facturación y pago. Nombres distintos, misma situación: el dinero se acabó.

CheapTokens funciona igual en principio: un saldo de prepago, pago por uso, un saldo para todos los modelos. Así que cuando algo falla, mira primero el saldo. Es una comprobación de diez segundos y descarta la causa más común.

2. Alcanzaste un límite de tasa#

DeepSeek documenta el HTTP 429 Rate Limit Reached como solicitudes que llegan demasiado rápido, o un límite de concurrencia o QPS superado. La solución es marcar el ritmo: menos solicitudes en paralelo, y un retardo de reintento creciente (1 s, 2 s, 4 s) en lugar de martillear el endpoint.

Una trampa. La API de Claude también devuelve 429 rate_limit_error cuando alcanzas el tope de gasto mensual de tu nivel, y esa respuesta no tiene cabecera retry-after. Así que un 429 que nunca se despeja tras esperar puede ir de dinero, no de velocidad. Si esperar no ayuda, vuelve a la causa 1.

3. La clave es incorrecta#

El HTTP 401 es un problema de clave en ambas documentaciones: DeepSeek lo lista como clave de API incorrecta, Claude como authentication_error. Las razones habituales son un espacio o salto de línea extra copiado con la clave, una clave que fue eliminada o regenerada, y una clave enviada a la dirección equivocada. Una clave de un servicio no funciona en la URL de otro servicio. Para CheapTokens la URL base es https://api.cheaptokens.dev/v1.

Para los demás errores que puedes encontrar al conectar, consulta Errores de conexión comunes y cómo solucionarlos.

4. El prompt no cabe en la ventana de contexto#

La ventana de contexto cuenta todo lo que el modelo lee en una solicitud: el prompt del sistema, todo el historial de la conversación, tu nuevo mensaje, y espacio para la respuesta. En CheapTokens, las ventanas de los modelos de nuestro catálogo son:

Un chat no tiene memoria propia. El cliente envía todo el historial de nuevo con cada solicitud, así que cada solicitud es más grande que la anterior. Aquí tienes un chat inventado para mostrar el crecimiento (números redondos, a modo de ilustración): un prompt del sistema de 1.000 tokens, y cada turno añade unos 500 tokens de pregunta y 1.500 tokens de respuesta, 2.000 en total.

1.000 + 30 × 2.000 = 61.000 tokens

Ese es el tamaño del historial tras 30 turnos. Cada uno de esos tokens cuenta como entrada de nuevo en la siguiente solicitud. La solicitud 31 lleva ese historial de 61.000 tokens más la nueva pregunta de 500 tokens, así que su entrada es de 61.500 tokens. Con una respuesta de 1.500 tokens en MiniMax-M2.7 cuesta $0.0033. Aquí tienes los tres modelos para la misma solicitud, con el precio de OpenRouter para comparar:

El mismo chat llena la ventana más pequeña en unos cien turnos:

(200.000 − 1.000) / 2.000 = 99,5

Cuando se desborda, el proveedor rechaza la solicitud. El código de estado varía según el proveedor, así que lee el cuerpo del error. El 413 request_too_large de Claude, por ejemplo, va del tamaño de la solicitud en bytes (32 MB para Messages), un límite distinto del de la ventana de tokens.

Qué hacer:

• Descarta los turnos más antiguos, o reemplázalos por un resumen breve.
• No pegues un documento entero cuando la tarea necesita un capítulo.
• Pasa a un modelo con una ventana mayor si de verdad necesitas el texto completo.

5. La respuesta se cortó#

Aquí no hay error, y eso es lo que hace confuso este caso. El modelo simplemente se detuvo porque alcanzó max_tokens o el límite de salida propio del modelo. En el formato Chat Completions la señal es finish_reason: "length" en la elección.

En CheapTokens, DeepSeek-V4-Flash puede devolver hasta 32.768 tokens por respuesta; GLM-5.3-Flash y MiniMax-M2.7 hasta 8.192. Si tu max_tokens es menor que eso, súbelo. Si ya estás en el límite, divide el trabajo ("escribe la parte 1 de 3") o pide al modelo que continúe desde la última frase.

La salida de MiniMax-M2.7 tiene un precio de $0.15 por 1M de tokens, y eso es más barato que OpenRouter en salida.

El mismo problema con distintos nombres#

Los proveedores etiquetan las mismas causas de forma diferente. Esto es lo que dice su documentación a fecha de 20 de octubre de 2026:

Fuentes: códigos de error de DeepSeek, errores de la API de Claude. Ninguna de las dos páginas muestra fecha de publicación, así que la fecha de comprobación es la nuestra.

La conclusión: no adivines por el texto. Los errores vuelven como JSON con un objeto error que contiene un type y un message. Compara por el estado y el tipo, porque el texto del mensaje cambia.

Mira qué vuelve realmente#

Este fragmento imprime el estado y el cuerpo de una solicitud fallida y el finish_reason de una exitosa. Es un esbozo de diagnóstico, no un registro de pruebas: ejecútalo con tu propia clave y lee lo que obtienes.

# 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

Si la comprobación apunta al saldo#

Recarga el saldo y envía la solicitud de nuevo. Los precios en CheapTokens son fijos por modelo, no hay horas punta, y un saldo cubre todos los modelos, así que no necesitas una recarga aparte para cada uno. Las tarifas actuales están aquí:

Introduce tu propio volumen en la tabla de costes antes de recargar. Recarga tu saldo cuando los números cuadren, y si quieres estimar primero una carga de trabajo mayor, consulta Cómo estimar el coste de un agente de IA.