Rate limits
Scrivete il client sugli header, non su un numero
Le quote variano per piano e cambiano nel tempo. La forma della policy no: leggi gli header, applica backoff con jitter e usa il percorso massivo per il lavoro massivo.
- Applicato per
- Organizzazione
- Segnalato da
- Header di risposta
- Risoluzione
- Contabilizzato a parte
Definition
Come sono applicati i limiti di frequenza dell’API?
I limiti sono applicati per organizzazione e per classe di endpoint, e comunicati a ogni risposta tramite header che indicano il limite, la quota residua e l’orario di reset. La risoluzione pubblica del passaporto è contabilizzata separatamente dalla tua quota, perché una raffica di scansioni non deve consumare il budget di una pipeline di emissione.
A client written against the headers keeps working when a quota changes. A client written against a number from a documentation page does not, and fails at the least convenient moment.
Classi
Non tutti gli endpoint sono contabilizzati allo stesso modo
| Class | Example | How it is governed |
|---|---|---|
| Public resolution | A consumer scanning a data carrier | Caching and edge capacity, not your quota |
| Read | Fetching a passport or an object history | Account quota, generous, cache-friendly |
| Write | Issuing a passport, appending an event | Account quota, lower ceiling than read |
| Bulk | Back catalogue import, historic event backfill | Asynchronous job with its own concurrency limit |
| Credential operations | Issuing or verifying a signed claim | Metered separately; cryptographic work is not free |
Header
Che cosa vi dice ogni risposta
RateLimit-Limit: the ceiling for this endpoint class
RateLimit-Remaining: what is left in the current window
RateLimit-Reset: seconds until the window resets
Retry-After: present on 429 — honour this first
# Back off with jitter. A fixed interval across many workers
# turns one brief limit into a sustained one.
const delay = Math.min(2 ** attempt * base, ceiling);
await sleep(delay * (0.5 + Math.random() / 2));Progettazione del client
Che cosa fa un client ben educato
Legge gli header
Si adatta alla soglia corrente invece di presumere un valore documentato.
Ritenta con jitter
Ritardo casuale, così i worker paralleli non ritentano all’unisono.
Usa il percorso massivo
Il recupero dello storico passa dalla modalità massiva, non da un ciclo su un endpoint a risorsa singola.
Separa le pipeline
Emissione e rendicontazione su chiavi distinte, così l’una non può affamare l’altra.
Limita i propri tentativi
Si arrende e segnala l’errore anziché ritentare all’infinito.
Avvisa prima del limite
Avvisi sulla soglia residua, così il primo segnale non è un 429 in produzione.
Risposte
Domande frequenti
Quali sono i limiti reali?
Dipendono dal vostro piano e dalla classe di endpoint, e sono indicati nel vostro contratto anziché qui. Un numero pubblicato sarebbe superato nel giro di una release, e chi dimensionasse su di esso scoprirebbe il limite reale in produzione. Leggete piuttosto gli header: sono sempre aggiornati.
Come dovrebbe reagire un client a un 429?
Rispetta `Retry-After` se presente, altrimenti applica un backoff esponenziale con jitter e limita il numero di tentativi. Ritentare subito, o a intervallo fisso da molti worker, trasforma un limite breve in uno prolungato: la calca che fa di un piccolo problema un disservizio.
La risoluzione pubblica del passaporto è limitata allo stesso modo?
No. La risoluzione è pubblica, cacheabile e per natura a raffiche: è quindi governata da cache e capacità di edge, non dalla tua quota. Un prodotto che diventa virale non deve consumare la quota da cui dipende la tua pipeline di emissione, ed è per questo che i due percorsi sono contabilizzati separatamente.
Come carichiamo un ampio catalogo storico?
Attraverso il percorso di import massivo e non ciclando sull’endpoint della singola risorsa. Il massivo è progettato per il throughput e gira in modo asincrono con un job da interrogare; l’endpoint per risorsa è progettato per la latenza. Usare quello sbagliato è la causa più comune di limitazione di frequenza autoinflitta.
I limiti si applicano per chiave o per organizzazione?
Per organizzazione, con visibilità per chiave. Conta quando delimiti le chiavi per servizio: un servizio che si comporta male può consumare il budget condiviso, e il dettaglio per chiave è ciò che ti permette di trovarlo in fretta anziché per esclusione.
Next step
Dicci i tuoi volumi prima di costruire
Dimensione del catalogo, ritmo di emissione e picco stagionale. Preferiamo dimensionare bene il piano piuttosto che farti scoprire un limite in produzione.