Grenzen (Rate-Limits)

Die Minutengrenzen gelten in einem gleitenden Fenster: gezählt werden die Aufrufe der letzten 60 Sekunden, nicht die seit der vollen Minute.

Grenzen für Importe

Damit ein missbrauchtes Token den Import Ihrer Organisation nicht blockieren kann, gelten für POST /v1/tenant-imports eigene Grenzen:

Offen ist ein Import, bis alle Datensätze in der Verwaltung übernommen oder gelöscht sind. Die für Ihre Organisation gültigen Werte und die Zahl offener Importe stehen unter Administration → API-Zugänge; bei einer Überschreitung nennt error.details Grenze und Stand (z. B. { "limit": 50, "open": 50 }). Brauchen Sie mehr, wenden Sie sich an den Support — die Grenzen lassen sich je Organisation anheben. Eine Wiederholung mit bereits verwendetem Idempotency-Key zählt nicht als neuer Import. Nicht mehr benötigte API-Importe geben Sie selbst frei: DELETE /v1/tenant-imports/{id} (siehe Import abbrechen).

Kopfzeilen zum Kontingent

Sobald das Token bekannt ist, tragen alle Antworten — auch Fehler wie 400, 403, 404 oder 409 — die Köpfe X-RateLimit-Limit (Grenze des Tokens je Minute: lesend oder schreibend), X-RateLimit-Remaining (noch freie Aufrufe) und X-RateLimit-Reset (Sekunden, bis alle bisher gezählten Aufrufe aus dem gleitenden Fenster gefallen sind; höchstens 60). Ohne bekanntes Token fehlen sie: bei 401, bei einer unbekannten Adresse (route_not_found) und bei 503 vor der Prüfung. Bei 429 rate_limited nennt der Kopf Retry-After die Wartezeit in Sekunden bis zum nächsten möglichen Aufruf (auch bei der Grenze je Organisation); X-RateLimit-Reset hat dann denselben Wert. Warten Sie mindestens so lange und verdoppeln Sie die Wartezeit bei wiederholten 429- oder 503-Antworten.

429 im Detail: Sonderfälle

Jedes 429 trägt Retry-After (ganze Sekunden, mindestens 1) — das ist die verbindliche Wartezeit. Die Zahl hängt von der ausgelösten Grenze ab; X-RateLimit-Remaining sagt bei den Sonderfällen unten nichts über den Grund, denn es zählt weiter die Minutengrenze des Tokens.

Minutengrenze (häufigster Fall)

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23
X-Request-Id: req_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Zu viele Anfragen. Bitte nach der in Retry-After genannten Zeit erneut versuchen."
  },
  "request_id": "req_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
}

Replay-Grenze eines Webhooks

HTTP/1.1 429 Too Many Requests
Retry-After: 1800
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset: 1800
X-Request-Id: req_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Für diesen Webhook wurden in der letzten Stunde schon 1000 Zustellungen erneut eingestellt (Höchstgrenze). Bitte nach der in Retry-After genannten Zeit erneut versuchen.",
    "details": {
      "limit": 1000,
      "retry_after": 1800
    }
  },
  "request_id": "req_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"
}

Was X-RateLimit-Reset bedeutet: Bei normalen Antworten die Sekunden, bis alle bisher gezählten Aufrufe aus dem gleitenden Minutenfenster gefallen sind (höchstens 60). Bei einer 429 mit Retry-After trägt es denselben Wert wie Retry-After — bei den Stundengrenzen also bis zu 3600, nicht nur bis 60. Planen Sie die Wiederholung nach Retry-After; wiederholen Sie die Anfrage bei Replay und Importen unverändert, schreibende Aufrufe mit demselben Idempotency-Key. Ein Replay, der an der Stundengrenze scheitert, hat nichts eingestellt; lassen Sie nicht mehrere Prozesse gleichzeitig wiederherstellen.