Claude API 429 rate_limit_error — cause e soluzione affidabile

Un 429 dall'API Claude significa che hai superato uno dei limiti al minuto di Anthropic: richieste, token in input o token in output. La soluzione raramente è «aspettare più a lungo»: bisogna rispettare retry-after, aggiungere backoff con jitter e distribuire i picchi. Ecco la procedura completa.

L’errore

risposta (HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

Cause e soluzioni in breve

Causa	Soluzione
Raggiunto il limite di richieste al minuto (RPM)	Accoda le richieste lato client; rispetta l'intestazione retry-after prima di riprovare.
Raggiunto il limite di token in input al minuto (ITPM) — prompt grandi, poche richieste	Riduci il contesto recuperato e abilita il prompt caching, così i token memorizzati non vengono conteggiati nei piani supportati.
Raggiunto il limite di token in output al minuto (OTPM)	Imposta max_tokens in modo realistico: OTPM è spesso il primo limite per le generazioni lunghe.
Traffico a raffiche (il cron avvia tutto a :00)	Aggiungi jitter agli orari; distribuisci i job batch nell'arco del minuto.

Leggi la risposta prima di riprovare

Anthropic restituisce un'intestazione retry-after con i secondi da attendere e il messaggio di errore indica quale limite hai superato. Riprovare immediatamente senza leggerla è il modo in cui un singolo 429 diventa una tempesta di 429.

Aggiungi backoff esponenziale con jitter

Ripeti solo gli status ripetibili (429, 500, 529), mai gli errori di autenticazione o validazione. Questo snippet funziona senza modifiche direttamente con Anthropic o con qualsiasi endpoint compatibile con OpenAI:

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Riduci i token, non solo le richieste

Se il messaggio parla di limiti dei token, il solo backoff non basta. Riduci i segmenti recuperati, limita max_tokens e attiva il prompt caching: anche un grande prompt di sistema stabile, pari al 10% della frequenza di input, riduce la pressione su ITPM.

Se chiami tramite Kunavo

Chiamare Claude tramite Kunavo non elimina magicamente i limiti di frequenza, ma cambia l'economia degli errori: le richieste fallite, inclusi i 429, non vengono mai addebitate, e il dashboard di utilizzo per chiave mostra esattamente quale chiave e quale modello stanno generando il picco, così puoi distribuirlo. Lo stesso snippet di backoff precedente funziona senza modifiche: cambia solo base_url. I limiti di frequenza sono un tetto al throughput, non un prezzo — per sapere quanto costa realmente una chiamata Claude per 1M di token, con l'elenco ufficiale di Anthropic accanto al nostro, consulta il tabella dei prezzi dell’API Claude di Anthropic.

Domande frequenti

Passare a un livello di utilizzo Anthropic superiore elimina i 429?

I livelli di utilizzo superiori aumentano i limiti al minuto, quindi i 429 diventano meno frequenti, ma qualsiasi limite fisso può essere raggiunto da un picco di traffico. Il codice di produzione deve comunque usare il backoff, indipendentemente dal livello.

Devo riprovare subito dopo un 429?

No: rispetta l'intestazione retry-after oppure usa un backoff esponenziale con jitter se è assente. I retry immediati prolungano la finestra limitata e possono causare un blocco più lungo.

Le richieste 429 fallite costano?

Anthropic non addebita le richieste rifiutate, e nemmeno Kunavo: le richieste fallite non vengono mai fatturate. Il costo di un 429 è la latenza, non il denaro.

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.