Fehler

Fehler teilen sich einen gemeinsamen Envelope (siehe den Überblick). Verzweigen Sie nach code, protokollieren Sie meta.request_id und behandeln Sie message als englischen Text für Menschen.

Client-Fehler

Code	Status	Bedeutung und Vorgehen
validation_failed	400	Ein Feld hat die Validierung nicht bestanden. field nennt es; details erklärt. Korrigieren Sie das Feld.
bad_request	400	Die Anfrage konnte überhaupt nicht gelesen werden: fehlerhaftes JSON, ein defekter Content-Encoding-Stream, ein abgebrochener Body. Es gibt kein Feld zu korrigieren; prüfen Sie die Übertragung.
validation_error	400	X-Account-Id wurde an einen Endpunkt gesendet, der ihn verbietet (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Der Paginierungs-Cursor ist älter als 24 Stunden. Beginnen Sie die Auflistung neu.
unauthenticated	401	Fehlendes oder ungültiges Token. Aktualisieren Sie die Sitzung oder prüfen Sie den Schlüssel.
invalid_signature	401	Eine Webhook-Signatur konnte nicht verifiziert werden. Siehe Webhooks.
forbidden	403	Das Token ist gültig, aber die Berechtigung fehlt.
account_context_mismatch	403	X-Account-Id stimmt nicht mit dem Konto des Tokens überein. Die Vorstellung des Clients vom aktuellen Unternehmen ist veraltet; lesen Sie sie erneut aus der Sitzung.
not_found	404	Die Ressource existiert nicht oder gehört zu einem anderen Konto oder einer anderen Website. Die API unterscheidet die beiden Fälle nie.
conflict	409	Zustandskonflikt: optimistische Sperre, Eindeutigkeitsbedingung oder eine im aktuellen Zustand nicht erlaubte Aktion (zum Beispiel Schreiben in eine zusammengeführte Konversation).
idempotency_key_conflict	409	Der Idempotency-Key wurde mit einem anderen Body wiederverwendet.
payload_too_large	413	Der Body überschreitet das Limit für diese Endpunktgruppe.
unsupported_media_type	415	Falscher Content-Type.
unprocessable	422	Gültiges JSON, aber eine Geschäftsregel hat es abgelehnt (zum Beispiel ein Buchungszeitfenster außerhalb der Arbeitszeiten).
storage_quota_exceeded	422	Das Konto hat das Speicherlimit seines Tarifs erreicht. details enthält used_bytes, quota_bytes und requested_bytes; geben Sie Speicher frei oder wechseln Sie in einen höheren Tarif.
rate_limited	429	Langsamer. Beachten Sie Retry-After und details.retry_after_seconds.

Server-Fehler

Code	Status	Bedeutung und Vorgehen
internal_error	500	Unerwarteter Fehler. Einmal wiederholen, dann den Support mit der request_id kontaktieren.
upstream_unavailable	502	Das Gateway konnte den Dienst überhaupt nicht erreichen. Eine kurze Wiederholung ist meist erfolgreich.
service_unavailable	503	Geplante Wartung oder ein offener Circuit Breaker. Nach dem Header Retry-After wiederholen.
ai_vendor_out_of_funds	503	Ihr KI-Anbieter hat den Aufruf aus Abrechnungsgründen abgelehnt (ein 402 oder ein Kontingent-429 vom Anbieter). Laden Sie das Konto beim Anbieter auf; eine Wiederholung hilft nicht.
upstream_timeout	504	Der Dienst hat nicht rechtzeitig geantwortet. Wiederholen, wenn retry_after vorhanden ist.

Wiederholen

Wiederholen Sie 429, 502, 503, 504 und Netzwerkfehler mit exponentiellem Backoff und senden Sie bei der Wiederholung denselben Idempotency-Key, damit ein Schreibvorgang nie doppelt angewendet wird. Wiederholen Sie keine 4xx außer 429.