Ratenlimits und Kontingente

Zwei Arten von Limits halten die API für alle schnell:

Das Ratenlimit eines Schlüssels: wie viele Anfragen pro Sekunde er senden darf, mit einem Burst für kurze Spitzen.
Die Kontingente der Organisation: wie viele Anfragen alle ihre Schlüssel zusammen pro Minute, pro Tag und pro Monat senden dürfen.

Beide hängen vom Tarif der Organisation ab. Jede Antwort zeigt Ihnen, wo Sie stehen, sodass ein gut programmierter Client nie raten muss.

Ratenlimit eines Schlüssels

Jeder Schlüssel erhält eine gleichmäßige Rate und einen Burst. Der Burst erlaubt Ihnen, so viele Anfragen auf einmal zu senden; danach sind Anfragen mit der gleichmäßigen Rate erlaubt.

Klasse	Rate	Burst
`basic`	5 Anfragen pro Sekunde	25
`standard`	20 Anfragen pro Sekunde	100
`high`	50 Anfragen pro Sekunde	250

Die Klasse ergibt sich aus dem Tarif der Organisation. GET /v1/me zeigt Klasse, Rate und Burst des aufrufenden Schlüssels (rate_limit). Das Limit gilt für den Schlüssel als Ganzes, gleichgültig, wie viele API-Server Ihre Anfragen bedienen.

Die Streaming-Endpunkte POST /v1/chat (mit oder ohne "stream": true) und GET /v1/jobs/stream liegen außerhalb des Ratenlimits des Schlüssels: Diese Endpunkte verbrauchen es nicht, und ihre Header RateLimit enthalten kein Element "key". Für die Kontingente der Organisation zählen sie dennoch, jeder einmal, beim Start der Anfrage. Für Fragen gelten eigene Limits, die unten beschrieben sind.

Kontingente der Organisation

Ein Tarif kann Anfragekontingente für die Organisation festlegen: pro Minute, pro Tag und pro Monat. Die Zeitfenster sind Kalenderzeiträume in UTC: Eine Minute beginnt bei :00 Sekunden, ein Tag um 00:00 UTC, ein Monat am ersten Tag um 00:00 UTC. Jede Anfrage mit einem Schlüssel oder einem OAuth-Token der Organisation zählt, unter jeder Adresse. Eine Streaming-Anfrage zählt einmal, beim Start, egal wie lange sie dauert; ist ein Kontingent aufgebraucht, wird sie wie jede andere Anfrage mit 429 abgelehnt. Eine mit 429 abgelehnte Anfrage zählt nicht.

Die Header

Jede Antwort auf eine Anfrage mit einem Schlüssel enthält die Limits, die für sie gelten:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy und RateLimit folgen dem IETF-Entwurf RateLimit header fields for HTTP. Jeder Eintrag ist ein Limit:

Eintrag	Bedeutung
`"key"`	Das Ratenlimit des Schlüssels. `q` ist der Burst, `w` die Anzahl Sekunden, in denen sich ein aufgebrauchter Burst wieder auffüllt.
`"minute"`, `"day"`, `"month"`	Ein Kontingent der Organisation, falls der Tarif eines vorsieht. `q` ist das Kontingent, `w` das Zeitfenster in Sekunden.
`r` (in `RateLimit`)	Wie viele Anfragen unter diesem Limit noch übrig sind.
`t` (in `RateLimit`)	Sekunden, bis dieses Limit wiederhergestellt ist.

X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset melden das strengste dieser Limits in einfacherer Form, für Clients, die vor RateLimit geschrieben wurden. X-RateLimit-Reset ist in Sekunden angegeben.

Wenn ein Limit erreicht ist

Die API antwortet mit 429 Too Many Requests und einem Header Retry-After in Sekunden:

Code	Bedeutung
`api.rate_limited`	Der Schlüssel hat schneller gesendet, als seine Rate erlaubt. `Retry-After` beträgt meist ein bis zwei Sekunden.
`api.quota_exceeded`	Ein Kontingent der Organisation ist aufgebraucht. `details` nennt, welches, und wann es zurückgesetzt wird.

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Warten Sie die Zeit aus Retry-After ab und wiederholen Sie die Anfrage. Wiederholen Sie POST und PATCH mit demselben Idempotency-Key. Die Hilfsfunktionen für Wiederholungen unter Fehler erledigen beides.

Auch andere Limits des Tarifs antworten mit 429 und Retry-After, zum Beispiel die Anzahl der Fragen pro Tag (limits.questions) oder gleichzeitig laufende Antworten (limits.concurrent_answers). Behandeln Sie sie auf dieselbe Weise.

Unter den Limits bleiben

Lesen Sie RateLimit und werden Sie langsamer, wenn r niedrig wird, statt auf ein 429 zu warten.
Verteilen Sie Massenarbeit über die Zeit und verwenden Sie Batch-Endpunkte, wo es sie gibt: Ein Batch mit 100 Dokumenten ist eine Anfrage.
Fragen Sie Änderungen nicht in einer engen Schleife ab. Abonnieren Sie Webhooks oder lesen Sie den Ereignis-Feed alle paar Sekunden.
Betreiben Sie parallele Worker mit einem gemeinsamen Limiter. Mehrere Prozesse mit einem Schlüssel teilen sich ein Ratenlimit.
Fragen Sie Ihren Ansprechpartner bei Sursa nach einer höheren Klasse, wenn Ihre Integration mehr braucht.