Rate Limits
Jede Anfrage zählt gegen ein festes 60-Sekunden-Fenster. Welcher Zähler gilt, hängt davon ab, wie du dich authentifizierst: API-Schlüssel bekommen das größte Budget, angemeldete Sitzungen ein großzügiges, anonymer Verkehr ein kleines. Ist das Budget aufgebraucht, antwortet die API mit 429 und sagt dir, wie lange du warten musst.
Die drei Buckets
Der Limiter wählt pro Anfrage genau einen Bucket. Die folgenden Limits sind die Standardwerte; Betreiber können sie anpassen, lies deshalb die Antwort-Header, statt Zahlen fest zu verdrahten.
apiKey | pro API-Schlüssel | 1000 Anfragen / min |
authenticated | pro Benutzer (Sitzung) | 600 Anfragen / min |
anonymous | pro Client-IP | 30 Anfragen / min |
Health- und Doku-Pfade (/health, /meta/version, /docs und /openapi) werden nie gedrosselt.
Antwort-Header
Jede gedrosselte Route legt ihre Richtlinie in der Antwort offen:
X-RateLimit-Limit | Erlaubte Anfragen im aktuellen Fenster für deinen Bucket. |
X-RateLimit-Window-Seconds | Länge des Fensters in Sekunden (60). |
X-RateLimit-Bucket | Der angewendete Bucket: anonymous, authenticated oder apiKey. |
Retry-After | Nur bei einem 429: Sekunden Wartezeit vor dem nächsten Versuch. |
Erfolgreiche Antworten tragen zusätzlich Varianten pro Bucket mit dessen Namen als Suffix, z. B. X-RateLimit-Remaining-apiKey (verbleibende Anfragen im Fenster) und X-RateLimit-Reset-apiKey (Sekunden bis zum Zurücksetzen des Fensters).
Die 429-Antwort
Eine gedrosselte Anfrage liefert das Standard-Fehlerformat mit dem stabilen Code RATE_LIMITED. Entwickle gegen den Code, zeige die Nachricht an.
{ "error": { "code": "RATE_LIMITED", "message": "ThrottlerException: Too Many Requests", "traceId": "01JGME0Z4E8B3T3Y5F0V9K2QRD" }}Wiederholen mit Backoff
Halte dich an Retry-After, wenn der Header da ist, und nimm sonst exponentielles Backoff. Kombiniere Wiederholungen verändernder Anfragen mit einem Idempotency-Key, damit ein erneutes Senden nie ein Duplikat erzeugt.
async function callWithRetry(request, maxRetries = 3) { for (let attempt = 0; ; attempt++) { const res = await request(); if (res.status !== 429 || attempt === maxRetries) return res; const seconds = Number(res.headers.get('Retry-After') ?? 2 ** attempt); await new Promise((resolve) => setTimeout(resolve, seconds * 1000)); }}Strenger begrenzte Bereiche
- Bei KI-Endpunkten (Chat, Belege, Sprache, Exporte) kommt eine zweite Drossel pro Benutzer und Haushalt obendrauf: standardmäßig eine Burst-Stufe von 10 Anfragen pro Minute plus eine Dauerstufe von 200 pro Stunde.
- Auth-Endpunkte unter /auth/* haben einen eigenen Brute-Force-Limiter: 10 Versuche pro IP und Minute sowie 5 pro Konto, mit exponentieller Sperre von bis zu einer Stunde, beantwortet mit 429 und dem Code TOO_MANY_REQUESTS.
- Alle Limits sind vom Betreiber einstellbar. Maßgeblich sind die Antwort-Header, nicht die Zahlen auf dieser Seite.