HTTP 429 Too Many Requests: attendi e riprova nel modo giusto
HTTP 429 Too Many Requests
HTTP 429 Too Many Requests: Retry-After e backoff | We.Inc
Cosa significa uno stato 429, come leggere Retry-After e codice di retry con backoff esponenziale e jitter. Pianifica il tuo calendario di retry con il calcolatore.
Una risposta 429 significa che il server ti sta applicando un rate limit: questo client ha inviato in una finestra di tempo più richieste di quante ne consenta. Smetti di inviare per un po'. Se la risposta contiene un header Retry-After, attendi quel tempo; altrimenti riprova con un backoff esponenziale più un jitter casuale, così molti client non riprovano tutti nello stesso istante.
Leggere una risposta 429
Parte
Cosa dice
Cosa deve fare il tuo client
Stato 429
Troppe richieste in un dato intervallo di tempo
Metti in pausa questo client, non bombardare il server
Retry-After: 120
Attendi 120 secondi (forma con ritardo in secondi)
Aspetta almeno quel tempo
Retry-After: Wed, 21 Oct 2026 07:28:00 GMT
Attendi fino a quell'ora (forma HTTP-date)
Sottrai l'ora attuale, poi aspetta
Nessun Retry-After
Il server non ha dato indicazioni
Usa un backoff esponenziale con jitter
Caching
Un 429 non deve essere salvato da una cache
Non servire mai più tardi un 429 salvato
Imposta il primo ritardo, il tetto massimo e quanti retry consenti, poi scegli uno stile di jitter. Il calcolatore elenca l'intervallo di attesa per ogni tentativo e il totale nel caso peggiore, così puoi vedere se il tuo client si arrende prima che la finestra del server si azzeri.
Inserisci il ritardo base in millisecondi, cioè il ritardo usato prima del primo retry.
Inserisci il tetto, l'attesa più lunga che una singola pausa possa mai avere.
Scegli quanti retry consentire e uno stile di jitter.
Leggi gli intervalli per tentativo e il totale, poi copia il codice corrispondente qui sotto.
Rispetta Retry-After al posto del tuo calendario ogni volta che il server lo invia. Il server sa quando si azzera la sua finestra, tu no.
Riprova solo le richieste che si possono ripetere in sicurezza. Una POST di pagamento ritentata senza una chiave di idempotenza può addebitare due volte.
Limita il numero di retry oltre al ritardo, e mostra un errore chiaro quando sono finiti.
Quando controlli il server, restituisci 429 con Retry-After invece di scartare o rallentare le richieste in silenzio, così i client ben scritti possono adattarsi.
Domande frequenti
Il 429 è un errore del client o del server?
Appartiene alla classe 4xx, quindi descrive il comportamento del client: troppe richieste. Sul server non c'è nulla di rotto. La soluzione è inviare meno richieste o distribuirle nel tempo.
Cosa contiene Retry-After?
Un numero di secondi da attendere, come 120, oppure una data HTTP dopo la quale puoi riprovare. Il tuo client dovrebbe gestire entrambe le forme.
Perché aggiungere il jitter al backoff esponenziale?
Senza jitter ogni client che ha fallito nello stesso momento riprova di nuovo nello stesso momento, ricreando il picco. Un'attesa casuale dentro ogni finestra distribuisce i retry.
Perché il rate limit di nginx restituisce 503 invece di 429?
Il modulo limit_req rifiuta con 503 a meno che tu non lo cambi. Aggiungi limit_req_status 429; accanto alla riga limit_req così i client vedono il codice più preciso.
Una CDN può mettere in cache una risposta 429?
Non deve. La RFC 6585 dice che le risposte con codice di stato 429 non devono essere salvate da una cache, così ogni client riceve una risposta aggiornata quando il limite viene rimosso.
Chi invia 429 e perché
API, form di login ed endpoint di ricerca contano le richieste per utente, per chiave o per indirizzo IP e rifiutano quelle in eccesso. La specifica lascia il conteggio al server, quindi un'API può limitare al minuto e un'altra al giorno.
La risposta dovrebbe spiegare il limite nel body, e può aggiungere Retry-After per dire quanto attendere.
I tre stili di backoff del calcolatore
Il backoff esponenziale semplice raddoppia l'attesa ogni volta fino al tetto: min(cap, base * 2^attempt). Il full jitter sceglie un'attesa casuale tra zero e quel numero. L'equal jitter ne tiene metà e rende casuale l'altra metà, il che garantisce una pausa minima.
Il full jitter distribuisce meglio il carico, ed è per questo che è un default sensato. L'equal jitter è adatto ai client che non devono mai riprovare all'istante.
Codice client che rispetta il 429
fetch con Retry-After e full jitter
Legge entrambe le forme di Retry-After, ripiega sul full jitter e si ferma dopo un numero fisso di retry.
Inviare 429 dal tuo server
nginx: limite per IP e risposta con 429
limit_req rifiuta con 503 di default; limit_req_status lo cambia in 429.
Com'è fatta la risposta
Un body breve che spiega il limite, e un Retry-After in secondi.
Calcolatore del calendario di retry
Ritardo base (ms)
Tetto per attesa (ms)
Retry
Stile di jitter
Full jitter
Equal jitter
Nessun jitter
Attesa prima di ogni retry
Retry
Attesa minima
Attesa massima
Caso peggiore prima di arrendersi: {v}
Usa numeri interi maggiori di zero, con il tetto almeno pari al ritardo base.