HTTP 429 e Backoff Esponenziale
In questa pagina
Gestione del Superamento dei Limiti
Non appena la tua applicazione raggiunge i limiti di RPM (richieste al minuto) o TPM (token al minuto), l’API Grok risponde con un codice di stato HTTP 429 (Too Many Requests). Leggi questo codice per quello che è: non un’interruzione del servizio, ma un segnale di controllo del flusso. L’API ti sta dicendo “rallenta”, non “è rotto”. La differenza tra un’integrazione robusta e una fragile sta nel modo in cui il tuo codice interpreta questa distinzione. Un errore 429 gestito male non rimane mai isolato: si propaga attraverso la coda, poi nei servizi chiamanti, e finisce come un incidente visibile all’utente finale.
Cosa Non Fare
La reazione istintiva quando una richiesta fallisce è reinviarla immediatamente. Questo è esattamente l’errore da evitare. Eri già oltre la tua quota; reinviando subito, consumi una chiamata aggiuntiva che fallirà anch’essa e prolunghi il periodo di blocco invece di accorciarlo. Un retry infinito peggiora le cose bloccando thread inutilmente. Al contrario, trattare il 429 come un errore permanente e rinunciare priva il tuo utente di un risultato che sarebbe arrivato pochi secondi dopo. L’approccio giusto sta nel mezzo: riprova, ma aspetta, e aspetta sempre più a lungo ogni volta.
Backoff Esponenziale
Il principio consiste nel raddoppiare il ritardo dopo ogni tentativo fallito, aggiungendo una variazione casuale chiamata jitter.
import time
import random
def call_with_retry(request, max_retries=5):
for attempt in range(max_retries):
response = send_request(request)
if response.status_code != 429:
return response
base_delay = 2 ** attempt # 1, 2, 4, 8, 16 seconds
jitter = random.uniform(0, base_delay * 0.5)
delay = base_delay + jitter
time.sleep(delay)
raise Exception("Retry limit reached")
Il jitter merita attenzione perché è spesso la riga cancellata con la scusa che complica inutilmente il codice. Immagina trenta istanze del tuo servizio che ricevono un 429 nello stesso secondo. Senza jitter, calcolano tutte lo stesso ritardo e riprovano esattamente nello stesso momento: hai riprodotto il picco di carico identico, un secondo dopo, poi due, poi quattro. Questo è il fenomeno del thundering herd. La randomizzazione distribuisce i tentativi nel tempo e rompe questa sincronizzazione involontaria. Nota anche che il ritardo di base inizia da un secondo: non scendere mai sotto questa soglia per il primo tentativo.
Scalabilità: Regola Prima di Fallire
Su un’applicazione ad alto volume, reagire ai 429 non è più sufficiente; è meglio evitarli. Un limitatore di frequenza lato client limita il numero di chiamate concorrenti e impone una spaziatura minima tra gli invii, così il carico in uscita rimane sotto il tetto invece di testarlo costantemente.
import asyncio
from asyncio import Semaphore
# Limit to 25 requests/second (margin under the allowed 30 req/s)
semaphore = Semaphore(25)
async def limited_request(payload):
async with semaphore:
response = await send_request_async(payload)
await asyncio.sleep(1.0 / 25) # minimum spacing
return response
Nota il margine deliberato: 25 richieste al secondo invece delle 30 consentite. Questa riserva assorbe le irregolarità di rete e i picchi di traffico senza mai raggiungere il tetto.
Il circuit breaker completa la configurazione interrompendo le chiamate quando i fallimenti si accumulano. Quando è chiuso, le richieste passano normalmente. Dopo un numero definito di fallimenti consecutivi, si apre e rifiuta localmente tutte le richieste per una durata configurata: smetti di martellare un’API che ti sta rifiutando e i tuoi thread rimangono disponibili per il resto dell’applicazione. Quando il ritardo scade, passa allo stato semi-aperto e lascia passare una singola richiesta di test; se ha successo, il traffico normale riprende, altrimenti il contatore si resetta. Questo meccanismo protegge il tuo servizio tanto quanto l’API dall’altra parte.
Tratta il 429 come una Metrica
Un ultimo riflesso, spesso assente nelle integrazioni: strumentare il tasso di 429. Questo numero non misura la qualità del tuo codice di retry; misura l’adeguatezza del tuo piano tariffario rispetto al tuo traffico reale. Una curva che sale settimana dopo settimana segnala un sottodimensionamento ben prima che gli utenti si lamentino, e ti dà il tempo di agire con calma—distribuire il carico, prevedere un upgrade del piano—invece di improvvisare un venerdì sera.
Punti chiave
- Il codice HTTP 429 segnala il superamento dei limiti RPM o TPM
- Il backoff esponenziale con jitter è la strategia raccomandata da xAI
- In produzione, integra il backoff con un limitatore di frequenza lato client e un circuit breaker
- Non retryare mai immediatamente: attendi almeno 1 secondo prima del primo tentativo
- Monitora il tasso di 429 nelle tue metriche come indicatore di sottodimensionamento