Introduzione

Durante l'integrazione con le nostre API, i client possono occasionalmente ricevere una risposta HTTP 429 – Too Many Requests.
Questo segnala che la frequenza delle richieste inviate dal client ha temporaneamente superato i limiti consentiti.

La nostra implementazione del rate-limiting è stata sviluppata per tutelare la stabilità del sistema e assicurare un utilizzo equo tra tutti i client.

Il presente articolo illustra il funzionamento del rate limiter e le modalità con cui le applicazioni client dovrebbero gestire in modo sicuro le risposte 429.

Modello di limite valutazione (token bucket)

I limiti valutazione sono applicati per identità:

• Richieste autenticate → per ID utente
• Richieste non autenticate → per indirizzo IP

A ciascuna identità è associato un token bucket:

• ogni richiesta consuma un token
• i token vengono ricaricati a un tasso fisso di token al secondo
• in assenza di token disponibili → API risponde con HTTP 429
• quando i token tornano a essere disponibili → le richieste vengono elaborate correttamente

Gestione delle risposte 429: backoff esponenziale con jitter

I client devono implementare il backoff esponenziale con jitter, poiché l’API non specifica l’intervallo di attesa prima di ritentare.

Programma di backoff raccomandato

Perché il jitter?

In assenza di casualità, più client potrebbero ritentare simultaneamente, generando picchi sincronizzati che possono causare ulteriori risposte 429 e compromettere la stabilità del sistema.
Il jitter consente di distribuire nel tempo i tentativi di ritrasmissione, contribuendo a stabilizzare il processo di recupero.

Limite massimo di ritrasmissione

Per prevenire loop infiniti di ritrasmissione o guasti a cascata:

• ritardo massimo: 30–60 secondi
• tentativi massimi: 5–7
• al superamento del limite → interrompere i tentativi e restituire un errore a monte.

Cosa non fare

I client sono tenuti a rispettare le seguenti indicazioni:

❌ non ritentare immediatamente dopo un 429
❌ non effettuare ritentativi in parallelo
❌ non incrementare il volume delle richieste dopo il recupero
❌ non presumere l’esistenza di una finestra di frequenza o di una quota fissa
(ad esempio, “è possibile effettuare 10 richieste/sec” o “il limite si azzera alle :00”)

Esempio di pseudocodice

Di seguito è riportato un esempio generico di pseudocodice che illustra una possibile implementazione del backoff esponenziale con jitter.

Backoff esponenziale di base con jitter

function sendWithRetry(request):
    baseDelay = 500  // ms
    maxDelay = 60000 // ms
    maxAttempts = 7
    attempt = 0
    while attempt < maxAttempts:
        response = sendHttpRequest(request)
        if response.status != 429:
            return response
        attempt += 1
        // ritardo esponenziale
        delay = baseDelay * (2 ^ (attempt - 1))
        // jitter ±50%
        jitter = randomBetween(0.5, 1.5)
        delay = delay * jitter
        delay = min(delay, maxDelay)
        sleep(delay)
    throw "Superato il numero massimo di tentativi di ritrasmissione"

Cosa non offre il limite valutazione

L’attuale implementazione del limite valutazione non restituisce:

• header Retry-After
• quota residua per la finestra corrente
• informazioni sulla dimensione o sui limiti della finestra temporale

I client devono implementare una propria logica di backoff e considerare ogni 429 come un segnale per ridurre temporaneamente la frequenza delle richieste.

Riepilogo

• Un HTTP 429 indica che la frequenza delle richieste ha superato i limiti consentiti
• Il server non specifica quanto attendere prima di ritentare
• I client devono implementare il backoff esponenziale con jitter, adottando limiti rigorosi sui tentativi
• Evitare ritentativi paralleli e assunzioni sulle finestre di frequenza
• Lo pseudocodice sopra riportato illustra un comportamento di ritrasmissione corretto e sicuro.