Rate-Limits, Kontingente und Fair Use
Rate-Limits sind das, was jede Integration irgendwann trifft, meist um 02:00 Uhr in der Nacht der ersten vollen Datenladung. Wer ihre Form vorher kennt, entwirft die Integration anders — und das ist billiger, als es hinterher herauszufinden.
Die Zahlen
| Wert | |
|---|---|
| Dauerrate | 100 Requests pro Sekunde |
| Burst-Spielraum | 200 Requests |
| Geltungsbereich des Limits | Je Tenant — geteilt über alle Schlüssel und alle Benutzer |
| Antwort bei Überschreitung | 429 Too Many Requests mit einem Retry-After-Header |
| Laufende Zähler in Antworten | Keine — behandeln Sie das 429 als das Signal |
Der Burst-Spielraum ist ein Eimer, keine zweite Zuteilung: Eine kurze Spitze über 100 pro Sekunde wird absorbiert, eine anhaltende nicht. Momentane Peaks sind in Ordnung. Eine enge Schleife nicht.
Der Teil, der überrascht
Das Limit gilt je Tenant, nicht je Schlüssel. Jede Integration, die Sie betreiben, plus Ihre Storefront, plus alle, die im Cockpit klicken, schöpfen aus derselben Zuteilung.
Daraus folgt etwas, das man deutlich sagen sollte: Ein schlecht geschriebener Nachtjob kann Ihren Shop verschlechtern. Wenn der BI-Abzug um 20:00 Uhr mit voller Geschwindigkeit durch 200.000 Produkte läuft, konkurrieren die Käufer, die um 20:00 Uhr noch arbeiten, mit ihm — und Ihre Storefront kann ihnen das nicht erklären.
Drei Gewohnheiten folgen daraus:
- Legen Sie schwere Arbeit in ein Fenster, das niemand nutzt, und schreiben Sie die Fenster auf, damit nicht zwei Integratoren beide 02:00 Uhr wählen.
- Deckeln Sie die Parallelität in jeder Integration. Vier oder acht parallele Requests reichen meist; zweiunddreißig sind eine Methode, die gesamte Tenant-Zuteilung aus einem Job heraus zu verbrauchen.
- Geben Sie Zeitplänen Jitter. Sechs Jobs, die alle exakt zur vollen Stunde starten, erzeugen eine Spitze, die keiner von ihnen allein verursacht hat.
X-RateLimit-*-Header, eine Integration kann sich also nicht am Restzähler
entlangtasten. Der Vertrag ist schlichter: in vernünftigem Tempo laufen, und
bei einem 429 den Retry-After respektieren und zurückweichen. Bauen Sie
für die zweite Hälfte dieses Satzes.Um 429 herum entwerfen
Ein gut erzogener Client behandelt 429 als gewöhnlich, nicht als Ausnahme.
Retry-Afterlesen und mindestens so lange warten. Er ist keine Empfehlung.- Danach exponentiell zurückweichen, mit Jitter. 1 s, 2 s, 4 s, 8 s,
16 s — jeweils multipliziert mit einem Zufallsfaktor zwischen etwa 0,5
und 1,5. Ohne Jitter wiederholen alle parallelen Worker im Gleichschritt
und erzeugen die Spitze neu, die das
429verursacht hat. - Den Backoff deckeln — ein, zwei Minuten reichen — und die Zahl der Versuche ebenfalls.
- Laut aufgeben. Nach dem Deckel schlägt der Job fehl, mit Alarm. Ein Job, der ewig wiederholt, ist ein Job, der still seine Arbeit nicht tut.
- Ein
429nie als fehlgeschlagenen Schreibzugriff behandeln. Der Request wurde abgelehnt, bevor etwas passiert ist; ihn zu wiederholen ist immer sicher. Für einen Timeout gilt das nicht — siehe unten.
429 heißt: Es ist nichts passiert.
Ein Verbindungs-Timeout heißt: Sie wissen nicht, ob etwas passiert ist. Die
beiden brauchen unterschiedliche Behandlung, und der Unterschied ist genau
der Grund, warum Schreibzugriffe idempotent sein müssen — siehe
Eine Integration durchgängig testen.Wann eine Schleife ein Bulk-Job hätte sein sollen
Die meisten Rate-Limit-Vorfälle sind ein Designproblem im Drosselungskostüm. Das Erkennungszeichen ist eine Schleife.
| Was die Integration tut | Größenordnung | Besser |
|---|---|---|
GET /v1/products Seite für Seite, 60.000 Artikel nächtlich | 1.200 Requests | Ein Massenexport — ein Job, eine Datei |
PUT je Produkt, um 40.000 Preise zu aktualisieren | 40.000 Requests | Ein Massenimport einer Preisdatei |
GET /v1/inventories/stock/{sku} je SKU zur Bestandsauffrischung | Einer je Artikel | Eine Bestandsdatei, oder ein Live-Lesen nur dort, wo ein Käufer hinsieht |
/v1/orders alle 30 Sekunden nach neuen Bestellungen abfragen | 2.880 Requests am Tag, fast alle leer | Ein Webhook, plus stündlicher Abgleichs-Poll |
| Nach dem Listen jedes Bestelldetail einzeln holen | N+1 Requests | Ein Listenaufruf mit den Feldern, die Sie brauchen |
Die Bulk-Ebene existiert genau dafür. Sie verarbeitet Dateien bis zu einer Million Zeilen in CSV, JSON, XLSX und XML, läuft als Job, dessen Status Sie abfragen, statt als Request, auf den Sie warten, und verbraucht Ihre Sekunden-Zuteilung nicht Zeile für Zeile. Siehe Massenexporte.
Die Faustregel: Skaliert die Zahl der Requests mit der Zahl der Artikel, ist es die falsche Schnittstelle.
Kontingente auf den anderen Schnittstellen
Das Rate-Limit ist nicht die einzige Decke. Drei weitere sollten Sie kennen, bevor sie Sie überraschen.
Bulk-Jobs. Eine Datei ist ein Job, kein Request: Sie reichen sie ein, sie wird eingereiht, und Sie fragen ihren Zustand ab. Zwei praktische Grenzen — eine einzelne Datei ist in der Zeilenzahl begrenzt, und die Formate unterscheiden sich in der Verarbeitung. CSV und XML streamen Zeile für Zeile; JSON und XLSX werden zuerst in den Speicher gelesen, was sie für die allergrößten Dateien zur falschen Wahl macht. Teilen Sie einen riesigen Abzug in mehrere Dateien statt in eine einzige enorme.
Webhook-Zustellung. Zustellungen werden bei Fehlern Ihres Endpoints mit wachsenden Abständen wiederholt, und ein Ziel, das dauerhaft fehlschlägt, wird irgendwann automatisch deaktiviert, damit ein toter Endpoint keinen unendlichen Rückstau ansammelt. Das Zustellprotokoll wird für ein begrenztes Fenster aufbewahrt — lang genug, um das Problem der letzten Woche zu untersuchen, nicht lang genug für ein Archiv. Lesen Sie das Protokoll, statt sich auf es als Datenspeicher zu verlassen.
Event-Volumen aus Ihren eigenen Aktionen. Eine Massenbearbeitung über 30.000 Produkte kann 30.000 Events auslösen, und jedes wird zu einer Zustellung an jeden abonnierten Endpoint. Das ist ein Lasttest für den Server Ihres Integrators, den niemand angesetzt hat. Sagen Sie ihm Bescheid, bevor Sie eine Massenänderung fahren, und abonnieren Sie eng — siehe Events und Webhooks.
Ein Dimensionierungsgespräch, das sich früh lohnt
Bevor eine Integration gebaut wird, holen Sie sich vier Zahlen von dem, der sie baut:
- Requests je Lauf, bei Ihrem echten Datenvolumen — nicht dem der Sandbox.
- Parallelität — wie viele Requests gleichzeitig unterwegs sind.
- Das Fenster, in dem sie läuft.
- Was sie bei
429tut, in einem Satz.
Liegt die Antwort auf die erste Frage in den Zehntausenden, ist das Design falsch, und das jetzt zu sagen ist deutlich billiger. Lautet die Antwort auf die vierte „sie wiederholt", fragen Sie, wie oft und wie lange sie wartet.
Weiter
- Häufige API-Aufgaben nach Job — die Rezepte, jedes mit der Schnittstelle, die skaliert.
- Häufige API-Probleme —
429lesen, neben den anderen Codes.