# Drosselung und Rate-Limit-Kopfzeilen

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`.

> **Typ:** nachschlagen
> **Für wen:** Wer eine Anmeldung baut oder einen `429` einordnen muss.
> **Voraussetzung:** keine

## 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

```json
{ "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](/de/cli/output-and-exit-codes).

## Weiterführendes

- [Das Fehlerformat](/de/api/error-format)
- [Ausgabe als JSON und Exit-Codes](/de/cli/output-and-exit-codes)