Fouten

Fouten delen één envelop (zie het overzicht). Vertak op code, log meta.request_id en behandel message als Engelse tekst voor mensen.

Clientfouten

Code	Status	Betekenis en wat te doen
validation_failed	400	Een veld is niet door de validatie gekomen. field noemt het veld; details legt het uit. Corrigeer het veld.
bad_request	400	Het verzoek kon helemaal niet worden gelezen: ongeldige JSON, een kapotte Content-Encoding-stream, een afgebroken body. Er is geen veld om te corrigeren; controleer het transport.
validation_error	400	X-Account-Id is meegestuurd naar een endpoint dat hem verbiedt (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	De pagineringscursor is ouder dan 24 uur. Begin de lijst opnieuw.
unauthenticated	401	Ontbrekend of ongeldig token. Vernieuw de sessie of controleer de sleutel.
invalid_signature	401	Een webhookhandtekening kon niet worden geverifieerd. Zie Webhooks.
forbidden	403	Het token is geldig, maar het recht ontbreekt.
account_context_mismatch	403	X-Account-Id komt niet overeen met het account van het token. Het beeld van de client van het huidige bedrijf is verschoven; lees het opnieuw uit de sessie.
not_found	404	De resource bestaat niet of hoort bij een ander account of een andere site. De API maakt nooit onderscheid tussen die twee.
conflict	409	Statusconflict: optimistische vergrendeling, een uniciteitsbeperking of een actie die in de huidige status niet is toegestaan (bijvoorbeeld schrijven naar een samengevoegd gesprek).
idempotency_key_conflict	409	De Idempotency-Key is hergebruikt met een andere body.
payload_too_large	413	De body overschrijdt de limiet voor deze endpointfamilie.
unsupported_media_type	415	Verkeerde Content-Type.
unprocessable	422	Geldige JSON, maar een bedrijfsregel heeft het geweigerd (bijvoorbeeld een boekingsslot buiten werktijd).
storage_quota_exceeded	422	Het account heeft de opslaglimiet van het abonnement bereikt. details bevat used_bytes, quota_bytes en requested_bytes; maak ruimte vrij of upgrade.
rate_limited	429	Doe het rustiger aan. Respecteer Retry-After en details.retry_after_seconds.

Serverfouten

Code	Status	Betekenis en wat te doen
internal_error	500	Onverwachte fout. Probeer het één keer opnieuw en neem daarna contact op met support, met de request_id.
upstream_unavailable	502	De gateway kon de service helemaal niet bereiken. Een korte nieuwe poging slaagt meestal.
service_unavailable	503	Gepland onderhoud of een open circuit breaker. Probeer het opnieuw na de tijd in de header Retry-After.
ai_vendor_out_of_funds	503	Je AI-provider heeft de aanroep om factuurredenen geweigerd (een 402 of een quotum-429 van de leverancier). Vul het tegoed bij de leverancier aan; een nieuwe poging helpt niet.
upstream_timeout	504	De service heeft niet op tijd geantwoord. Probeer het opnieuw als retry_after aanwezig is.

Opnieuw proberen

Probeer 429, 502, 503, 504 en netwerkfouten opnieuw met exponentiële backoff, en stuur bij de nieuwe poging dezelfde Idempotency-Key mee, zodat een schrijfactie nooit twee keer wordt uitgevoerd. Probeer andere 4xx-fouten dan 429 niet opnieuw.