429 Too Many Requests: limiti di frequenza e falsi allarmi

Cosa significa un 429 e cosa arriva insieme a esso

429 è definito nell'RFC 6585 come lo stato per la limitazione di frequenza: il client ha inviato troppe richieste in un dato intervallo di tempo. La specifica lascia deliberatamente due cose aperte: come il server identifica il client, e come vengono contate le richieste. Ecco perché i limiti di frequenza differiscono così tanto tra i servizi.

In pratica, i server contano per indirizzo IP, per chiave API, per sessione, per account, o per combinazione di questi, e usano finestre fisse, finestre scorrevoli o token bucket. Due frequenze di richiesta identiche possono quindi andare bene su un endpoint ed essere bloccate su un altro dello stesso sito.

La risposta porta i segnali di cui hai bisogno:

• Retry-After è quello standard. L'RFC 9110 permette sia un numero di secondi sia una data HTTP, e un client ben educato aspetta quel tempo prima di riprovare.
• Le intestazioni di limite di frequenza come RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, oppure le varianti più vecchie X-RateLimit-, espongono il budget e quando si azzera. Sono convenzioni, non parte dell'RFC 9110, quindi controlla la documentazione dell'API per i nomi esatti.
• Il corpo dovrebbe spiegare il limite in termini leggibili da un essere umano. Molte API nominano quale quota è stata superata, il che risparmia molte congetture.

Un 429 non è memorizzabile in cache per impostazione predefinita, quindi gli intermediari non dovrebbero continuare a servirlo dopo che la finestra si è azzerata.

Limite di frequenza o interruzione reale?

Questi si confondono di continuo, perché entrambi appaiono come richieste fallite. I test per distinguerli sono rapidi:

• Il codice stesso. Un limite di frequenza risponde 429. Un server sovraccarico o in modalità manutenzione risponde 503. Entrambi possono portare Retry-After, motivo per cui le persone li confondono, ma significano cose diverse: 429 dice "tu specificamente stai inviando troppo", 503 dice "il servizio nel suo insieme non può accettare lavoro in questo momento". Vedi la guida al 503 per quel lato.
• Tempo di risposta. I limiti di frequenza rifiutano velocemente, di solito in millisecondi, perché la decisione viene presa prima che avvenga qualsiasi lavoro reale. Il sovraccarico risponde lentamente o va in timeout.
• Chi è interessato. Un limite di frequenza colpisce una identità client. Testa da un indirizzo IP diverso o con una chiave API diversa: se quello ha successo mentre il client limitato continua a fallire, è un limite, non un'interruzione.
• Lo schema nel tempo. La limitazione di frequenza è periodica e si risolve da sola. I fallimenti si raggruppano, poi si fermano esattamente quando la finestra si azzera, poi tornano. Un'interruzione non riprende educatamente secondo una pianificazione.
• Correlazione con il tuo stesso volume. Se i fallimenti sono iniziati quando hai alzato una frequenza di controllo, aggiunto worker paralleli o lanciato un job in batch, la causa è dal tuo lato della connessione.

Perché il monitoraggio può far scattare un 429 su se stesso

Il monitoraggio è una richiesta ripetuta da un piccolo insieme di indirizzi verso lo stesso URL, il che è vicino alla forma che i limitatori di frequenza sono costruiti per catturare. Un intervallo di controllo molto breve peggiora la situazione, perché controlli ogni minuto moltiplicati per molti URL monitorati si sommano rapidamente contro un budget per IP. Lo stesso vale per eseguire un controllo da molte ubicazioni contemporaneamente: l'origine vede un picco invece di un flusso costante, e i limiti sui picchi scattano per primi.

Conta anche la scelta dell'URL. Le pagine di ricerca, gli endpoint API e tutto ciò che scrive sono di solito limitati più severamente di una homepage statica. E se il monitoraggio e l'applicazione condividono una chiave API, i due competono per una singola quota. Il risultato è un monitor che segnala il sito come fallito mentre il sito è interamente sano, e un limitatore di frequenza che sta facendo correttamente il suo lavoro.

Come correggere un 429

1. Leggi le intestazioni della risposta prima di cambiare qualsiasi cosa:

   curl -sS -o /dev/null -D - https://example.com/api/items

   Retry-After e qualsiasi intestazione di limite di frequenza ti dicono il budget reale, il che batte indovinare gli intervalli.
2. Rispetta Retry-After. Riprovare immediatamente estende il blocco in molte implementazioni. Aspetta il tempo indicato.
3. Applica un backoff esponenziale con jitter nel codice client, così i client concorrenti non si sincronizzano e riprovano in un'ondata di massa.
4. Abbassa la frequenza delle richieste. Per il monitoraggio, sposta un endpoint controllato su un intervallo più lungo, oppure scagliona i controlli così che molte ubicazioni non scattino nello stesso secondo.
5. Monitora un URL economico e rappresentativo. Un endpoint di salute leggero o la homepage ti dice che il sito è attivo senza spendere la quota di cui hai bisogno per il traffico reale.
6. Esenta il client di monitoraggio al livello del limitatore. Metti in allowlist gli indirizzi delle postazioni di controllo, oppure dai al monitoraggio la propria chiave API con il proprio budget, così non compete mai con il traffico di produzione.
7. Se possiedi il limitatore, verifica che il limite sia giusto. Chiediti se il budget corrisponde all'uso reale, se è per IP quando dovrebbe essere per account, e se proxy condivisi o NAT aziendali stanno mettendo molti utenti dietro un unico indirizzo.

Sorvegliare i 429 senza causarli

I limiti di frequenza di solito compaiono prima per i client più impegnati, il che significa che i clienti paganti e le integrazioni li colpiscono prima di chiunque nel tuo team. Un controllo HTTP pianificato che fa un assert sul codice di stato atteso mostra un 429 come un evento distinto e con timestamp invece che come segnalazioni sparse di "l'API è instabile", e la tempistica ti dice se il limite è periodico o permanente. Imposta l'intervallo con attenzione: abbastanza frequente da notare i problemi rapidamente, abbastanza delicato da non essere mai il controllo stesso a far scattare il limite. La famiglia più ampia dei rifiuti, inclusi 401 e 403, è trattata nella panoramica 4xx.