Zum Inhalt springen
Szenera DeveloperHandbuch
API › Grundlagen › Drosselung und Rate-Limit-Kopfzeilen
Kapitel

Drosselung und Rate-Limit-Kopfzeilen

Welche Routen eine eigene Grenze haben, welches Kontingent an einem Schlüssel hängt, was die vier Kopfzeilen bedeuten und wie ein Client auf 429 reagiert.

4 Minuten LesezeitAPIStand: 25.10.2026

Auf dieser Seite

Bevor Sie loslegen

Für wen
Wer eine Anmeldung baut oder einen 429 einordnen muss.
Voraussetzung
keine

Zwei Dinge werden gedrosselt, aus zwei Gründen: die missbrauchsnahen Routen — Anmeldung, Anmelde-Link, Registrierung, Passwort-Zurücksetzen und die Rundläufe der Anbieter-Anmeldung — tragen jeweils eine eigene Grenze, und jeder Aufruf mit einem API-Schlüssel zählt zusätzlich gegen ein Kontingent, das dem Schlüssel gehört. Diese Seite nennt die Kopfzeilen, beide Grenzen und die richtige Reaktion auf 429.

Die Kopfzeilen

Jede Antwort, auf die eine Grenze wirkt, liefert den Stand des Fensters mit:

Kopfzeile Bedeutung
X-RateLimit-Limit erlaubte Anfragen im Fenster insgesamt
X-RateLimit-Remaining davon noch offen
X-RateLimit-Reset Zeitpunkt, an dem das Fenster neu beginnt, in Unix-Sekunden
Retry-After Sekunden bis zum nächsten erlaubten Versuch — nur bei Überschreitung (429)

Alle vier sind für Browser-Clients auf anderen Ursprüngen lesbar, ebenso X-Trace-Id, X-Correlation-Id und Server-Timing.

Die Antwort bei Überschreitung

{ "code": "RateLimit.Exceeded", "message": "Too many requests", "traceId": "trc_…" }

Status 429, dazu Retry-After. Ein zweiter Code desselben Bereichs, RateLimit.GlobalCircuitBreaker (ebenfalls 429), zeigt eine plattformweite Überlast-Sicherung an; die Reaktion ist dieselbe.

Die Grenzen der Anmelde- und Registrierungsrouten

Die Grenzen gelten je Fenster und je Zählmerkmal: „IP“ zählt je Absenderadresse, „IP+Adresse“ je Absenderadresse und E-Mail-Adresse im Rumpf.

Route Grenze
POST /v1/auth/identify 10 je Minute (IP+Adresse) und 40 je 10 Minuten (IP)
POST /v1/auth/login 5 je Minute (IP+Adresse)
POST /v1/auth/login/choose-organization 10 je Minute (IP)
POST /v1/auth/mfa/verify, POST /v1/auth/mfa/recovery-code 5 je Minute (IP)
POST /v1/auth/login/magic-link 5 je Minute (IP+Adresse)
POST /v1/auth/login/magic-link/consume 5 je Minute (IP)
POST /v1/auth/password-reset/request 5 je Minute (IP+Adresse)
POST /v1/auth/password-reset/consume 5 je Minute (IP)
POST /v1/auth/onboarding/consume 5 je Minute (IP)
GET /v1/auth/login/sso/{providerId} 20 je Minute (IP)
GET|POST /v1/auth/login/sso/callback 30 je Minute (IP)
GET /v1/auth/login/social 60 je Minute (IP)
GET /v1/auth/login/social/{provider} 20 je Minute (IP)
GET|POST /v1/auth/login/social/callback 30 je Minute (IP)
POST /v1/auth/login/exchange 10 je Minute (IP)
POST /v1/auth/sso-recovery/consume 5 je Minute (IP)
GET /v1/auth/signup 60 je Minute (IP)
POST /v1/auth/signup/start 3 je 10 Minuten (IP+Adresse) und 10 je 24 Stunden (IP)
POST /v1/auth/signup/verify, POST /v1/auth/signup/social 10 je Minute (IP)
POST /v1/auth/signup/complete, POST /v1/auth/signup/join 5 je Minute (IP)
POST /v1/tenants/me/sso/{providerId}/domains/{domain}/verify 10 je Minute (IP)

Weitere öffentliche und sitzungsgebundene Routen haben eigene Fenster — etwa die Einladungs-Annahme (GET|POST /v1/invitations/public/{token} und …/accept, je IP), der Auswertungs-Export (POST /v1/analytics/metrics/{metric}/export, je Organisation) und die USt-Id-Prüfung (POST /v1/me/billing-profile/vat-id/verify, je Organisation). Den Wert nennt die Beschreibung der Operation in der Referenz, wo sie ihn nennt; sonst zeigen ihn die Kopfzeilen der Antwort.

Das Kontingent je Schlüssel

Ein Aufruf mit einem Schlüssel ak_… zählt gegen ein Kontingent, das dem Schlüssel gehört — auf jeder Route, auch auf den lesenden ohne eigene Grenze. Der Grund ist die Bauart eines Automaten: Ein Mensch klickt, ein Skript fragt in einer Schleife, und gerade die billigen Lese-Wege legen einen Stapel am schnellsten lahm.

Was Wert
Vorgabe ein Wert der Umgebung in der Form <Anzahl>/<Fenster>, etwa 600/1m; das Fenster zählt in s, m oder h
Je Schlüssel beim Anlegen überschreibbar (Feld rateLimit in POST /v1/me/api-keys; null heißt „die Vorgabe der Umgebung“) — eine Rotation übernimmt den Wert
Gezählt wird je Schlüssel, nicht je Absenderadresse und nicht je Organisation
Kopfzeilen dieselben vier wie oben, an jeder Antwort
Bei Überschreitung 429 RateLimit.Exceeded mit Retry-After

Nicht betroffen sind Aufrufe aus einer angemeldeten Sitzung, Geräte, Abspieler und Betreiber-Schlüssel: Sie haben eigene Grenzen. Wirken auf einen Aufruf mehrere Regeln — etwa die Grenze der Anmelderoute und das Kontingent des Schlüssels —, zeigen die Kopfzeilen die knappste, und die zuerst gerissene Regel bestimmt den Fehlercode.

Was ein Client daraus macht: X-RateLimit-Remaining mitlesen und die eigene Schleife bremsen, bevor die Null erreicht ist. Ein Import, der zehntausend Medien anlegt, läuft mit einer kleinen Pause je Aufruf schneller durch als einer, der gegen die Wand fährt und wartet.

Die richtige Reaktion

Regel Warum
Retry-After abwarten, dann genau einmal wiederholen Jeder Versuch davor zählt ins Fenster und verlängert die Sperre.
X-RateLimit-Remaining beobachten und vor der Null bremsen Ein Client, der das Fenster kennt, sieht nie einen 429.
Nicht hämmern Wiederholungen im Sekundentakt füllen das Fenster, statt es zu leeren.

Die Kommandozeile beendet einen Aufruf mit 429 mit Exit-Code 8 (rate-limited) — siehe Ausgabe als JSON und Exit-Codes.

Weiterführendes