Rate Limits

Welche Grenze dich trifft, was jede Operation kostet und wie dein Client nach einer 429 wartet. Deinen eigenen Stand liefert GET /v1/rate_limit.

Kosten je Operation

Jeder Aufruf zieht Punkte vom Eimer ab. In der Referenz steht der Wert an jeder Operation als x-bodo-cost; kein Endpunkt ist kostenlos.

get · 1
list · 2
count · 2
Suche q · +5
create · 5
update · 5
delete · 10
Geld-Aktion · 10
Langer Lauf (202) · 10
Batch · Summe der Teile
me · 1
rate_limit · 1
openapi.json · 1
operations · events · 1

Ebenen

Die Antwort meldet immer die engste Grenze.

Ebene	Gilt für	Grenze
Schlüssel	einen Schlüssel	300 Punkte/min, Kapazität 600
Schreiben	einen Schlüssel	60 Schreibungen/min
Parallel	einen Schlüssel	6 gleichzeitige Aufrufe
Prinzipal	alle Schlüssel einer Person bzw. eines Dienstkontos	1.200 Punkte/min
Organisation	alle Schlüssel der Organisation	3.000 Punkte/min, ein Schlüssel höchstens 50 %
Löschen	einen Schlüssel	10/min und 300 je Tag, danach wird das Löschen pausiert
Datenabfluss	einen Schlüssel	10.000 gelesene Datensätze/h

Header

Nach dem IETF-Entwurf RateLimit-Header (Draft 11). Jede Antwort trägt beide Zeilen.

Normale Antwort, dann die Absage

RateLimit-Policy: "key";q=300;w=60, "org";q=3000;w=60
RateLimit: "key";r=12;t=41

HTTP/1.1 429 Too Many Requests
Retry-After: 41
RateLimit: "key";r=0;t=41

Beispielantwort

GET /v1/contacts?limit=100

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Content-Language: de

{
  "type": "https://developers.bodo-app.com/problems/RATE_LIMITED",
  "title": "Zu viele Anfragen",
  "status": 429,
  "detail": "Die Grenze dieses Schlüssels ist erreicht.",
  "instance": "/v1/contacts",
  "code": "RATE_LIMITED",
  "requestId": "req_01JBD8Y3K5M7Q2W9X4Z6T1V0NP"
}

Drei Arten von 429

Code	Bedeutung	Reaktion
RATE_LIMITED	deine Grenze ist erreicht	`Retry-After` abwarten
OVERLOADED	die Instanz ist ausgelastet	`Retry-After` abwarten, dann mit Zufallsabstand
QUOTA_EXHAUSTED	ein Kontingent ist verbraucht	nicht wiederholen, bis es zurückgesetzt ist

Für eine Drosselung kommt nie 403. Quota-Alarm: Wird ein Kontingent knapp oder der Abfluss ungewöhnlich hoch, bekommen der Besitzer des Schlüssels und die Org-Admins eine Mail und einen Eintrag in der Glocke.

Backoff

Wer nach einer 429 weiterfeuert (mehr als 50 Absagen in 60 s), wird für den Schlüssel 5 Minuten gesperrt.

Lies Retry-After (ganze Sekunden) oder genauer retryAfterMs aus dem Problem.
Warte so lange und lege einen kleinen Zufallsabstand darauf, damit nicht alle Clients gleichzeitig wiederkommen.
Fehlt der Header, verdopple die Wartezeit je Versuch (1, 2, 4, 8 s) und gib nach fünf Versuchen auf.
QUOTA_EXHAUSTED wiederholst du nicht: bis zum Zurücksetzen bleibt die Antwort gleich.

Die SDKs warten für dich@bodo/api und bodo-api wiederholen eine Antwort 429 oder 503 nach Retry-After, standardmäßig bis zu zweimal (maxRetries bzw. max_retries), mit demselben Idempotency-Key.