Errore "Not enough tokens": cosa significa e come risolverlo

"Not enough tokens" non è un solo errore. Le persone usano questa frase per cinque problemi diversi: il saldo è esaurito, le richieste arrivano troppo veloci, la chiave è sbagliata, il prompt non entra nella finestra di contesto del modello, oppure la risposta ha raggiunto il limite di output e si è interrotta a metà frase. Ognuno ha la sua correzione, e il modo più rapido per distinguerli è lo stato HTTP e il corpo dell'errore, non il testo del messaggio.

Trova il tuo sintomo nella tabella, esegui il controllo, applica la correzione.

Tre cose che "token" può significare#

La parola nel messaggio di errore indica tre grandezze diverse.

• Saldo. I token sono ciò per cui paghi, quindi "finito i token" spesso significa "finito i soldi". Su un servizio prepagato questo è il saldo.
• Un limite al minuto. I limiti possono essere contati in richieste o in token al minuto. Se ne colpisci uno, la correzione è aspettare e inviare meno alla volta.
• Dimensione della finestra. La finestra di contesto è quanti token il modello può leggere in una richiesta, il tuo prompt e la sua risposta insieme.

E una cosa che non significa mai: una chiave API non è una scorta di token. La chiave identifica il tuo account. Ciò che si esaurisce è il saldo dietro di essa, o un limite a essa associato. Se l'unità in sé è nuova per te, inizia da What is a token in AI?.

1. Il saldo è esaurito#

La documentazione dell'API di DeepSeek descrive HTTP 402 Insufficient Balance come "You have run out of balance". L'API di Claude usa 402 billing_error per problemi di fatturazione e pagamento. Nomi diversi, stessa situazione: i soldi sono finiti.

CheapTokens funziona allo stesso modo in linea di principio: saldo prepagato, paghi man mano che usi, un saldo per tutti i modelli. Quindi quando qualcosa si rompe, guarda prima il saldo. È un controllo di dieci secondi ed esclude la causa più comune.

2. Hai colpito un rate limit#

DeepSeek documenta HTTP 429 Rate Limit Reached come richieste che arrivano troppo veloci, o un limite di concorrenza o QPS superato. La correzione è scandirle: meno richieste parallele, e un ritardo di retry crescente (1 s, 2 s, 4 s) invece di martellare l'endpoint.

Una trappola. L'API di Claude restituisce 429 rate_limit_error anche quando raggiungi il tetto di spesa mensile del tuo tier, e quella risposta non ha header retry-after. Quindi un 429 che non si risolve mai dopo l'attesa può riguardare i soldi, non la velocità. Se aspettare non aiuta, torna alla causa 1.

3. La chiave è sbagliata#

HTTP 401 è un problema di chiave in entrambe le documentazioni: DeepSeek lo elenca come chiave API sbagliata, Claude come authentication_error. Le ragioni abituali sono uno spazio o un a capo di troppo copiato con la chiave, una chiave cancellata o rigenerata, e una chiave inviata all'indirizzo sbagliato. Una chiave di un servizio non funziona all'URL di un altro servizio. Per CheapTokens il base URL è https://api.cheaptokens.dev/v1.

Per gli altri errori che puoi incontrare durante la connessione, vedi Common connection errors and how to fix them.

4. Il prompt non entra nella finestra di contesto#

La finestra di contesto conta tutto ciò che il modello legge in una richiesta: il system prompt, l'intera cronologia della conversazione, il tuo nuovo messaggio e lo spazio per la risposta. Su CheapTokens, le finestre dei modelli nel nostro catalogo sono:

Una chat non ha memoria propria. Il client invia di nuovo l'intera cronologia a ogni richiesta, quindi ogni richiesta è più grande della precedente. Ecco una chat inventata per mostrare la crescita (numeri tondi, a scopo illustrativo): un system prompt di 1.000 token, e ogni turno aggiunge circa 500 token di domanda e 1.500 token di risposta, 2.000 in totale.

1.000 + 30 × 2.000 = 61.000 token

Questa è la dimensione della cronologia dopo 30 turni. Ognuno di quei token conta di nuovo come input alla richiesta successiva. La 31ª richiesta porta quella cronologia di 61.000 token più la nuova domanda di 500 token, quindi il suo input è di 61.500 token. Con una risposta di 1.500 token su MiniMax-M2.7 costa $0.0033. Ecco tutti e tre i modelli per la stessa richiesta, con il prezzo di OpenRouter per confronto:

La stessa chat riempie la finestra più piccola in circa un centinaio di turni:

(200.000 − 1.000) / 2.000 = 99,5

Quando va in overflow, il provider rifiuta la richiesta. Il codice di stato varia da provider a provider, quindi leggi il corpo dell'errore. Il 413 request_too_large di Claude, per esempio, riguarda la dimensione della richiesta in byte (32 MB per Messages), un limite diverso dalla finestra di token.

Cosa fare:

• Elimina i turni più vecchi, oppure sostituiscili con un breve riassunto.
• Non incollare un intero documento quando il task richiede un solo capitolo.
• Passa a un modello con una finestra più grande se ti serve davvero il testo completo.

5. La risposta è stata troncata#

Qui non c'è errore, ed è questo che rende il caso confuso. Il modello si è semplicemente fermato perché ha raggiunto max_tokens o il limite di output del modello stesso. Nel formato Chat Completions il segnale è finish_reason: "length" sulla choice.

Su CheapTokens, DeepSeek-V4-Flash può restituire fino a 32.768 token per risposta; GLM-5.3-Flash e MiniMax-M2.7 fino a 8.192. Se il tuo max_tokens è inferiore, alzalo. Se sei già al limite, dividi il lavoro ("scrivi la parte 1 di 3") oppure chiedi al modello di continuare dall'ultima frase.

L'output di MiniMax-M2.7 è prezzato a $0.15 per 1M token, ed è più economico di OpenRouter sull'output.

Lo stesso problema con nomi diversi#

I provider etichettano le stesse cause in modo diverso. Questo è ciò che dice la loro documentazione al 20 ottobre 2026:

Fonti: DeepSeek error codes, Claude API errors. Nessuna delle due pagine mostra una data di pubblicazione, quindi la data del controllo è la nostra.

La conclusione: non tirare a indovinare dal testo. Gli errori tornano come JSON con un oggetto error che contiene un type e un message. Fai il match sullo stato e sul tipo, perché il testo del messaggio cambia.

Guarda cosa torna davvero#

Questo snippet stampa lo stato e il corpo di una richiesta fallita e il finish_reason di una riuscita. È uno schizzo diagnostico, non un log di test: eseguilo con la tua chiave e leggi cosa ottieni.

# 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 il controllo punta al saldo#

Ricarica il saldo e invia di nuovo la richiesta. I prezzi su CheapTokens sono fissi per modello, non ci sono ore di punta, e un saldo copre tutti i modelli, quindi non serve una ricarica separata per ciascuno. Le tariffe attuali sono qui:

Inserisci il tuo volume nella tabella dei costi prima di ricaricare. Top up your balance quando i numeri ti tornano, e se vuoi prima stimare un carico di lavoro più grande, vedi How to estimate the cost of an AI agent.