Rate limits
Schrijf de client tegen de headers, niet tegen een getal
Quota verschillen per abonnement en veranderen in de tijd. De vorm van het beleid niet: lees de headers, wacht af met jitter, en gebruik het bulkpad voor bulkwerk.
- Toegepast per
- Organisatie
- Gesignaleerd door
- Responsheaders
- Resolutie
- Apart geteld
Definition
Hoe worden API-rate limits toegepast?
Limieten gelden per organisatie en per endpointklasse, en worden bij elk antwoord meegegeven via headers met de limiet, de resterende ruimte en het resetmoment. Publieke paspoortresolutie wordt apart geteld van uw quotum, want een scanpiek mag het budget van een uitgiftepijplijn niet opsouperen.
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.
Klassen
Niet alle endpoints worden gelijk geteld
| 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 |
Headers
Wat elk antwoord u vertelt
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));Clientontwerp
Wat een net gedragen client doet
Leest de headers
Past zich aan de actuele limiet aan in plaats van uit te gaan van een gedocumenteerd getal.
Wacht af met jitter
Willekeurige vertraging, zodat parallelle workers niet in de pas opnieuw proberen.
Gebruikt het bulkpad
Het inlezen van bestaande historie gaat via bulk, niet via een lus over een enkelvoudig endpoint.
Scheidt de pijplijnen
Uitgifte en rapportage op verschillende sleutels, zodat de een de ander niet kan uithongeren.
Begrenst zijn retries
Geeft het op en meldt de fout in plaats van eindeloos opnieuw te proberen.
Waarschuwt vóór het plafond
Waarschuwingen over de resterende limiet, zodat het eerste signaal geen 429 in productie is.
Antwoorden
Veelgestelde vragen
Wat zijn de werkelijke limieten?
Zij hangen af van uw abonnement en van de endpointklasse, en staan in uw overeenkomst en niet hier. Een gepubliceerd getal zou binnen één release verouderd zijn, en een integrator die daarop dimensioneert ontdekt de echte limiet in productie. Lees in plaats daarvan de headers — die zijn altijd actueel.
Hoe zou een client op een 429 moeten reageren?
Respecteer `Retry-After` als die aanwezig is, wacht anders exponentieel af met jitter, en begrens het aantal pogingen. Direct opnieuw proberen, of op een vast interval vanuit veel workers, verandert een korte limiet in een aanhoudende — de stormloop die van een klein probleem een storing maakt.
Wordt publieke paspoortresolutie op dezelfde manier gelimiteerd?
Nee. Resolutie is publiek, cachebaar en per definitie piekerig, dus zij wordt geregeld door caching en edge-capaciteit, niet door uw quotum. Een product dat viraal gaat mag niet het quotum opsouperen waar uw uitgiftepijplijn van afhangt; daarom worden de twee paden apart geteld.
Hoe laden wij een grote bestaande catalogus in?
Via het bulk-importpad en niet door het single-resource-endpoint in een lus aan te roepen. Bulk is ontworpen voor doorvoer en draait asynchroon met een job die u pollt; het endpoint per resource is ontworpen voor latency. Het verkeerde kiezen is de meest voorkomende oorzaak van zelfveroorzaakte rate limiting.
Gelden limieten per sleutel of per organisatie?
Per organisatie, met zicht per sleutel. Dat telt wanneer u sleutels per dienst scopet: één zich misdragende dienst kan het gedeelde budget opsouperen, en de uitsplitsing per sleutel is hoe u die snel vindt in plaats van door uitsluiting.
Next step
Vertel ons uw volumes voordat u bouwt
Catalogusomvang, uitgiftetempo en de seizoenspiek. Wij dimensioneren het plan liever goed dan dat u in productie tegen een plafond aanloopt.