Fehler - Chatarmin CX Docs

Jeder Public API v1 Fehler nutzt dieses JSON-Envelope:

{
  "success": false,
  "code": "TICKET_NOT_FOUND",
  "message": "Ticket not found",
  "request_id": "req_abc123",
  "retry_after": 42
}

Feld	Beschreibung
`success`	Immer `false`
`code`	Maschinenlesbarer Code — darauf in Integrationen prüfen
`message`	Menschenlesbar — nur loggen, nicht für Logik-Branches
`request_id`	Korrelations-ID für Support und Logs
`details`	Optional strukturierter Kontext (Validierung)
`retry_after`	Bei Rate-Limit-Fehlern — Wartezeit in Sekunden

Fehlercodes

Code	HTTP	Wann
`API_KEY_REQUIRED`	401	Header `cx-api-key` fehlt
`INVALID_API_KEY`	401	Schlüssel unbekannt oder widerrufen
`API_KEY_ORG_MISSING`	401	Schlüssel ohne Organisationsbindung
`FORBIDDEN_SCOPE`	403	Scope für Route fehlt
`VIEW_NOT_FOUND`	404	Unbekannte `view_id`, Cross-Org oder für Agent unsichtbar
`TICKET_NOT_FOUND`	404	Ticketnummer existiert in der Org nicht
`ATTACHMENT_NOT_FOUND`	404	Unbekannte Anhang-ID, oder gehört zu einer anderen Organisation
`INVALID_FILTER`	400	Ungültiger Filter oder View-Konfiguration
`VALIDATION_ERROR`	400	Ungültige Query-Parameter oder unbekannte Felder
`IDEMPOTENCY_KEY_CONFLICT`	400	Gleicher `Idempotency-Key` mit anderem Request-Body wiederverwendet
`IDEMPOTENCY_KEY_IN_PROGRESS`	409	Der erste Request mit diesem `Idempotency-Key` läuft noch — kurz erneut versuchen
`RATE_LIMIT_EXCEEDED`	429	Rate Limit erreicht
(keiner)	500	Unerwarteter Serverfehler — mit Backoff wiederholen

VALIDATION_ERROR kann details mit Feld-Fehlern enthalten (z. B. ungültiges UUID-Format bei view_id).

Beim Support angeben: