Rate limits
Schreiben Sie den Client gegen die Header, nicht gegen eine Zahl
Kontingente unterscheiden sich je Tarif und ändern sich mit der Zeit. Die Gestalt der Richtlinie nicht: Header lesen, mit Jitter warten und für Massenarbeit den Bulk-Pfad nutzen.
- Angewendet je
- Organisation
- Signalisiert durch
- Antwort-Header
- Auflösung
- Getrennt gezählt
Definition
Wie werden API-Ratenbegrenzungen angewendet?
Limits gelten je Organisation und je Endpunktklasse und werden bei jeder Antwort über Header mitgeteilt, die Limit, verbleibendes Kontingent und Reset-Zeit nennen. Die öffentliche Passauflösung wird getrennt von Ihrem Kontingent gezählt, denn ein Scan-Burst darf nicht das Budget einer Ausstellungspipeline verbrauchen.
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
Nicht alle Endpunkte werden gleich gezählt
| 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
Was Ihnen jede Antwort sagt
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));Client-Design
Was ein wohlerzogener Client tut
Liest die Header
Passt sich dem aktuellen Kontingent an, statt eine dokumentierte Zahl anzunehmen.
Wartet mit Jitter
Zufällige Verzögerung, damit parallele Worker nicht im Gleichtakt wiederholen.
Nutzt den Bulk-Pfad
Nachladen von Bestandsdaten läuft über Bulk, nicht über eine Schleife auf einem Einzelressourcen-Endpunkt.
Trennt die Pipelines
Ausstellen und Berichten auf getrennten Schlüsseln, sodass eines das andere nicht aushungern kann.
Begrenzt seine Wiederholungen
Gibt auf und meldet den Fehler, statt unbegrenzt zu wiederholen.
Warnt vor dem Erreichen der Grenze
Warnungen zum verbleibenden Kontingent, damit das erste Anzeichen kein 429 im Produktivbetrieb ist.
Antworten
Häufig gestellte Fragen
Wie hoch sind die tatsächlichen Limits?
Sie hängen von Ihrem Tarif und von der Endpunktklasse ab und stehen in Ihrem Vertrag, nicht hier. Eine veröffentlichte Zahl wäre binnen eines Releases veraltet, und wer danach dimensioniert, würde das reale Limit in der Produktion entdecken. Lesen Sie stattdessen die Header — die sind immer aktuell.
Wie sollte ein Client auf ein 429 reagieren?
Beachten Sie `Retry-After`, falls vorhanden, warten Sie andernfalls exponentiell mit Jitter und begrenzen Sie die Versuchszahl. Sofort zu wiederholen — oder in festem Intervall über viele Worker — macht aus einem kurzen Limit ein dauerhaftes: die Herde, die aus einem kleinen Problem einen Ausfall macht.
Wird die öffentliche Passauflösung genauso ratenbegrenzt?
Nein. Die Auflösung ist öffentlich, cachebar und erwartbar stoßweise; sie wird daher durch Caching und Edge-Kapazität geregelt, nicht durch Ihr Kontingent. Ein viral gehendes Produkt sollte nicht das Kontingent verbrauchen, auf das Ihre Ausstellungspipeline angewiesen ist — deshalb werden beide Wege getrennt gezählt.
Wie sollten wir einen großen Altbestand laden?
Über den Bulk-Import-Pfad und nicht durch Schleifen über den Einzelressourcen-Endpunkt. Bulk ist auf Durchsatz ausgelegt und läuft asynchron mit einem Job, den Sie abfragen; der Einzelressourcen-Endpunkt ist auf Latenz ausgelegt. Den falschen zu nutzen ist die häufigste Ursache für selbst verursachte Rate-Limits.
Gelten Limits je Schlüssel oder je Organisation?
Je Organisation, mit Sichtbarkeit je Schlüssel. Das zählt, wenn Sie Schlüssel je Dienst begrenzen: Ein sich falsch verhaltender Dienst kann das gemeinsame Budget verbrauchen, und die Aufschlüsselung je Schlüssel ist der Weg, ihn schnell zu finden statt durch Ausschluss.
Next step
Nennen Sie uns Ihre Volumina, bevor Sie bauen
Katalogumfang, Ausstellungsrate und die saisonale Spitze. Wir dimensionieren den Plan lieber richtig, als dass Sie im Produktivbetrieb an eine Decke stoßen.