Leadde Logo

Comprendere i Limiti di Frequenza delle API

Una lezione concisa che spiega cosa sono i limiti di frequenza delle API, perché vengono implementati, gli errori comuni nei tentativi e modelli efficaci come il backoff esponenziale.
LDi Leadde Aggiornato 22 agosto 2026

Come un Limite di Frequenza Decide se la Tua Richiesta Verrà Eseguita

Un limite di frequenza stabilisce quante richieste un client può inviare in un dato intervallo e restituisce un errore 429 una volta superato. Questo limite esiste per impedire che un singolo client consumi una capacità destinata a tutti, ed è per questo che la risposta corretta è rallentare, piuttosto che inviare immediatamente la stessa richiesta.

Ritentare immediatamente è esattamente ciò che fanno la maggior parte delle prime integrazioni, trasformando un rifiuto temporaneo in uno prolungato. Il client raggiunge il limite, ritenta, estende l'intervallo di misurazione e finisce per essere rallentato molto più a lungo di quanto richiesto dal picco originale, solitamente mentre uno sviluppatore conclude che l'API non è affidabile. Sono volutamente escluse le configurazioni dei tuoi limiti: soglie per livello, permessi di burst e gli endpoint con limiti più stringenti appartengono alla documentazione versionata, non a un video che invecchia rapidamente.

Il template segue una richiesta attraverso otto scene: una sul perché esistono i limiti, una sull'intervallo e come viene conteggiato, una su cosa contiene una risposta 429, due sul backoff e perché il ritardo deve aumentare, una sul jitter e il 'thundering herd', una sulla lettura degli header dei limiti di frequenza e una sulla progettazione per raggiungere raramente il limite.

Come Spiegare il Backoff in Meno di Due Minuti

L'educazione degli sviluppatori compete con la documentazione che l'utente ha già aperta. Qualsiasi cosa che ripeta la pagina di riferimento viene chiusa entro venti secondi, quindi il modulo deve comunicare l'unica cosa che la documentazione spiega male: il modello di fallimento, piuttosto che il parametro.

Mostra la 'Tempesta di Retry' Prima della Soluzione

Mostra la 'Tempesta di Retry' Prima della Soluzione

Un client che ritenta ogni 200 millisecondi contro un limite già superato è l'intero problema, visibile in una sola scena. Il backoff arriva quindi come la soluzione ovvia, piuttosto che come una semplice raccomandazione.

Rendi Esplicito il Raddoppio

Un secondo, due, quattro, otto. Dichiarare la progressione è più rapido che definire il backoff esponenziale ed è ciò che uno sviluppatore implementa realmente.

Dai al Jitter il Suo Momento

Senza randomizzazione, ogni client rallentato ritenta simultaneamente e il tentativo di recupero diventa la prossima interruzione. Questa è la parte che la maggior parte delle integrazioni trascura e il motivo per cui esiste questo modulo.

Punta agli Header, Non ai Numeri

I limiti cambiano; gli header che li riportano no. Insegnare al client a leggere ciò che gli viene comunicato è meglio che codificare un valore fisso che sarà errato il trimestre successivo.

Parti dalla Documentazione API che Già Pubblichi

Carica la documentazione API, la guida all'integrazione inviata ai partner o i ticket di supporto dell'ultimo onboarding — massimo 200 MB, in formato PDF, DOC, DOCX, PPTX o TXT. Le scene tornano modificabili, il documento originale rimane intatto.

Allinealo con la Tua API

Usa i Tuoi Nomi di Header a Schermo

Usa i Tuoi Nomi di Header a Schermo

La denominazione degli header varia tra le piattaforme, e uno sviluppatore a cui viene mostrato un esempio generico dovrà comunque cercare i tuoi. Inserire i nomi reali nella scena elimina questo passaggio.

Spiega Cosa Succede Dopo Violazioni Ripetute

Spiega Cosa Succede Dopo Violazioni Ripetute

Alcune piattaforme rallentano, altre sospendono le chiavi, altre ancora avvisano un operatore umano. Essere espliciti sulle conseguenze cambia la serietà con cui un partner considera le indicazioni.

Stilizza le Didascalie per i Termini che Richiedono Precisione

Stilizza le Didascalie per i Termini che Richiedono Precisione

Codici di stato, nomi di header e valori di parametro sono facilmente fraintendibili all'ascolto, ma affidabili alla lettura. Scegli tra i nove stili di sottotitoli, mantieni lo stesso per tutta la serie per sviluppatori e assicurati che i termini di codice rimangano leggibili anche a dimensioni ridotte.

FAQ sui Limiti di Frequenza API

Un limite di frequenza regola la velocità in un breve intervallo, solitamente secondi o un minuto, ed è recuperabile attendendo. Una quota regola il volume totale in un periodo di fatturazione e non lo è. Confonderli porta i client a ritirarsi quando invece dovrebbero richiedere un aumento.

Leggere il valore 'retry-after' se fornito, attendere almeno per quel periodo, e poi ritentare con un ritardo che aumenta ad ogni fallimento successivo. Ritentare immediatamente o a intervalli brevi e fissi prolunga il rallentamento invece di risolverlo.

I nomi degli endpoint vanno bene e rendono il modulo più utile. Chiavi e token no, inclusi quelli scaduti, perché un video di formazione circola al di fuori del partner per cui è stato creato e vive molto più a lungo della credenziale.

Perché la richiesta fallita conta comunque nell'intervallo nella maggior parte delle implementazioni. Ogni tentativo spinge il client oltre il limite, quindi il tempo di attesa necessario per superarlo aumenta ad ogni tentativo di evitare di aspettare.

Controlla i Limiti Prima che lo Faccia la Produzione

Elabora la documentazione API che già pubblichi, poi perfeziona le scene prima della prossima integrazione con un partner.

avatar

Inizia con questo modello. Finisci con un video pronto da condividere.

Aggiungi la tua guida di onboarding o le pagine del centro assistenza e genera una bozza modificabile in pochi minuti.