Errore 429 rate_limit_error nell'API Claude — significato e soluzione

Il 429 significa "più lentamente", non "hai finito i soldi". La differenza conta: per il primo bisogna aspettare, per il secondo ricaricare — confonderli porta a ore di debug nel posto sbagliato.

L’errore

risposta (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

Cause e soluzioni in breve

Causa	Soluzione
Richieste al minuto oltre il limite del tuo account	Accoda le richieste e limita la concorrenza nel client, invece di inviarle tutte insieme.
Token al minuto oltre il limite	I prompt lunghi consumano la quota di token molto prima della quota di richieste. Riduci il contesto o suddividi il lavoro.
Più processi usano la stessa chiave	Il limite riguarda la chiave, non il processo. I worker paralleli si sommano sulla stessa quota.
Retry senza backoff	Riprovare immediatamente ti mantiene permanentemente oltre il limite. Il backoff esponenziale con jitter è obbligatorio.

Rispetta retry-after quando è presente

Quando la risposta contiene l'intestazione retry-after, non è un suggerimento: è il tempo esatto dopo il quale la richiesta viene nuovamente accettata. Aspettare meno garantisce un altro 429.

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

Limita la concorrenza alla fonte

La causa più comune non è il volume totale, ma il picco: venti richieste inviate nello stesso istante superano il limite che sessanta richieste distribuite nell'arco di un minuto non supererebbero. Un semaforo risolve ciò che il solo retry non risolve.

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

Conferma che sia un limite, non il saldo

Un 429 non significa mai che mancano crediti — quello è 402. Se il tuo log mescola i due casi, separali per stato prima di indagare: la correzione del 429 è la temporizzazione, quella del 402 è la ricarica. Ripetere un 402 fallisce per sempre.

Se chiami tramite Kunavo

Su Kunavo i limiti sono per chiave e il saldo è un portafoglio prepagato separato, quindi i due casi hanno stati diversi: 429 per il limite di frequenza e 402 quando il saldo non copre la chiamata — mai uno mascherato dall'altro. Le richieste rifiutate non vengono addebitate. Le tariffe per token, che determinano quanto ogni chiamata consuma dal saldo, sono disponibili nella nostra guida ai prezzi dell'API Claude.

Domande frequenti

429 significa che ho finito i crediti?

No. Il saldo insufficiente è 402. Il 429 riguarda la velocità: hai inviato troppe richieste o troppi token in poco tempo e aspettare risolve il problema.

Quanto devo aspettare?

Se è presente l'intestazione retry-after, esattamente quel tempo. In sua assenza, usa un backoff esponenziale a partire da 1–2 secondi con jitter, fino a un limite di 30–60 secondi.

Aumentare il limite risolve il problema?

Aiuta se il volume è davvero elevato, ma la maggior parte dei 429 deriva da brevi picchi. Limitare la concorrenza di solito risolve il problema senza modificare alcun limite.

Guide correlate

Ulteriori dettagli sul significato degli errori sono disponibili in riferimento agli errori; ottenere una chiave richiede un minuto tramite registrazione e la guida all’autenticazione.