Fehler, Idempotenz und Limits

Einheitliche Fehler, opaque Cursor, sichere Retries und die Limits der Private Beta.

12 Min. Lesezeit

Fehler-Envelope

Protokolliere request_id für Support und Korrelation. Unbekannte Codes behandelst du nach ihrer HTTP-Klasse; parse niemals den Nachrichtentext.

Errorjson

{
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "The supplied source version conflicts with the current snapshot.",
    "request_id": "req_01JABC",
    "details": {"current_source_version": 43}
  }
}

Fehlercodes

HTTP	Codes
400	invalid_request · invalid_cursor · invalid_grant · IDEMPOTENCY_KEY_REQUIRED · unsafe_webhook_url
401	authentication_required · invalid_token
403	insufficient_scope · installation_inactive
404	not_found
409	VERSION_CONFLICT · UNMAPPED_COURT · IDEMPOTENCY_CONFLICT · IDEMPOTENCY_IN_PROGRESS · endpoint_limit_reached · installation_exists · installation_state_changed
429	rate_limited
500	internal_error · idempotency_replay_failed
503	authorization_unavailable · rate_limit_unavailable · service_unavailable

Idempotency-Key

Jeder mutierende öffentliche POST benötigt einen Key mit 8 bis 200 Zeichen.
Gleicher Key und gleicher Request liefern das gespeicherte Ergebnis.
Gleicher Key mit anderem Request liefert 409 IDEMPOTENCY_CONFLICT.
Allgemeine Ergebnisse bleiben 24 Stunden gespeichert.
Der Installations-Exchange bleibt zusätzlich dauerhaft an den verbrauchten Code gebunden.
Buchungs-PUTs verwenden fachlich source_version.

Pagination

Standardlimit 50, Maximum 100
Cursor sind opaque Base64url-Werte
Cursor nie interpretieren oder selbst konstruieren
Bei has_more: true exakt next_cursor weiterreichen

Pagejson

{
  "data": [],
  "next_cursor": null,
  "has_more": false
}

Private-Beta-Limits

Beachte RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Bei 429 kommt Retry-After hinzu; verwende Backoff mit Jitter.

Limit	Wert
Requests	600 pro Minute je Installation und Club
Writes	höchstens 120 davon
WebSockets	5 gleichzeitig
Webhook-Endpunkte	10

Abhängigkeiten können fail-closed sein

Wenn Autorisierung, Tenant-Bindung oder verteiltes Rate Limiting nicht sicher geprüft werden kann, antwortet die API mit einem dokumentierten 503 statt Zugriff zu erlauben. Wiederhole sichere Reads mit Backoff; mutierende POSTs nur mit demselben Idempotency-Key und unverändertem Body.