HTTP 429: limiti API, retry e backoff senza errori

Quando un servizio risponde con HTTP 429 Too Many Requests, sta segnalando che il client ha superato un limite di richieste. Non si tratta sempre di un guasto: spesso è una protezione pensata per preservare stabilità, sicurezza e qualità del servizio.

Per chi gestisce integrazioni, script o applicazioni, il punto non è solo “riprovare”, ma capire quale soglia è stata superata e con quale strategia rientrare nei parametri senza peggiorare la situazione.

Perché compare il 429

Un 429 può dipendere da diversi fattori: troppe richieste in poco tempo, picchi su uno stesso token, limiti per IP, quote giornaliere o regole applicate a endpoint specifici. In alcuni casi il blocco è temporaneo; in altri indica che l’uso dell’API va riprogettato.

Il primo passo è leggere gli header della risposta. Alcune API indicano il numero massimo di richieste consentite, il residuo disponibile e il tempo da attendere prima di riprovare. Se presente, l’header Retry-After è spesso il riferimento più affidabile.

Controlli rapidi da fare

• Verificare se il limite è per IP, utente o chiave API.
• Controllare se il problema nasce in un singolo endpoint o in tutte le chiamate.
• Confrontare orario del blocco, volume richieste e job attivi.
• Leggere documentazione e header di rate limit.
• Capire se esistono quote distinte per lettura, scrittura o autenticazione.

Segnali utili nei log

Nei log applicativi cercare pattern ripetuti: stesso endpoint, stesso identificativo client, stessi intervalli di tentativo. Se il 429 appare subito dopo un deploy o l’avvio di un cron, il problema può essere un loop o una concorrenza non prevista.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0

Retry e backoff: come farli bene

La regola più importante è evitare retry aggressivi. Un ciclo immediato di richieste peggiora il carico e può prolungare il blocco. Meglio usare un backoff esponenziale, magari con una piccola componente casuale per evitare che più client ripartano insieme.

Se l’API fornisce un tempo preciso di attesa, rispettarlo. Se non lo fornisce, iniziare con pause brevi e aumentare gradualmente. In genere conviene anche fissare un numero massimo di tentativi, oltre il quale l’errore va propagato o messo in coda.

Un retry utile non è quello che insiste di più, ma quello che riparte nel momento giusto.

Ridurre il numero di richieste

Spesso la soluzione migliore è prevenire il 429 alla fonte. Si può:

• accorpare richieste quando l’API lo permette;
• introdurre cache lato client;
• evitare polling troppo frequente;
• usare webhook al posto di controlli continui;
• limitare le chiamate parallele;
• riutilizzare token e sessioni dove possibile.

In ambienti con più servizi, è utile applicare una coda centralizzata o un rate limiter interno, così da distribuire le richieste in modo prevedibile.

Monitoraggio e prevenzione

Un buon monitoraggio rende il 429 un segnale, non un’emergenza. Conviene tracciare tasso di errore, numero di retry, latenza media e saturazione delle quote. Se il valore cresce dopo una modifica, si individua subito la causa.

Per API critiche, è utile creare alert su soglie come: aumento improvviso dei 429, esaurimento della quota residua o crescita anomala delle richieste per minuto. Questo consente di intervenire prima che il servizio degradi per gli utenti finali.

Quando serve cambiare architettura

Se i 429 sono frequenti anche con retry corretti, il problema potrebbe essere strutturale. In quel caso conviene rivedere il design: meno polling, più eventi, batch più grandi, sincronizzazione differita o separazione tra traffico interattivo e processi in background.

In sintesi, un 429 va trattato come un’informazione preziosa. Leggere gli header, rispettare i tempi di attesa e ridurre le richieste superflue sono le mosse che fanno davvero la differenza.

Per approfondire la gestione dei limiti lato client, può essere utile consultare la documentazione ufficiale della piattaforma usata e le linee guida su MDN Web Docs.