Rate Limits - Chatarmin CX Docs

Public API v1 setzt pro Route Rate Limits, keyed by API-Schlüssel (Fallback: Client-IP ohne Schlüssel).

Limits nach Endpoint-Klasse

Klasse	Routen	Limit
Liste	`GET /tickets`, `GET /views`	60 Requests / Minute
Detail	`GET /tickets/:ticketNumber`, `GET /tickets/:ticketNumber/messages`	120 Requests / Minute

GET /health nutzt die Detail-Stufe. Listen- und Detail-Limits sind unabhängig — erschöpftes Listen-Budget blockiert Detail-Requests nicht.

Response-Header

Jede Antwort enthält Rate-Limit-Header:

Header	Bedeutung
`X-RateLimit-Limit`	Max. Requests im Fenster
`X-RateLimit-Remaining`	Verbleibende Requests
`X-RateLimit-Reset`	Unix-Zeitstempel für Fenster-Reset

Bei Überschreitung: 429 mit Code RATE_LIMIT_EXCEEDED und Header Retry-After (Sekunden). Im Error-Envelope kann zusätzlich retry_after stehen.

{
  "success": false,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded.",
  "request_id": "req_...",
  "retry_after": 42
}

Best Practices

Backoff bei 429 — Retry-After abwarten (oder exponentielles Backoff mit Jitter).
Keine engen Polling-Schleifen — sinnvolle Intervalle; Cursor-Pagination mit Backoff statt Listen-Endpoints hammern.
View-Metadaten cachen — GET /views ändert sich selten; Mapping id → Name/Filter cachen.
Gezielt Messages laden — Threads nur für benötigte Tickets, nicht für jede Listenzeile.

Legacy `/public/*`

Deprecated Legacy-Endpoints haben andere Limits (30–300 Requests / Minute je nach Route). Siehe Legacy-OpenAPI-Referenz während der Migration.