Foute

Foute deel een omslag (sien die oorsig). Vertak op code, teken meta.request_id aan, en behandel message as Engelse teks vir mense.

Kliëntfoute

Kode	Status	Betekenis en wat om te doen
validation_failed	400	’n Veld het validering gedruip. field noem dit; details verduidelik. Maak die veld reg.
bad_request	400	Die versoek kon glad nie gelees word nie: misvormde JSON, ’n gebreekte Content-Encoding-stroom, ’n afgebreekte liggaam. Daar is geen veld om reg te maak nie; kontroleer die vervoer.
validation_error	400	X-Account-Id is gestuur na ’n eindpunt wat dit verbied (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Die pagineringswyser is ouer as 24 uur. Begin die lys weer.
unauthenticated	401	Ontbrekende of ongeldige token. Verfris die sessie of kontroleer die sleutel.
invalid_signature	401	’n Webhook-handtekening kon nie geverifieer word nie. Sien Webhooks.
forbidden	403	Die token is geldig maar het nie die toestemming nie.
account_context_mismatch	403	X-Account-Id pas nie by die token se rekening nie. Die kliënt se idee van die huidige maatskappy het weggedryf; lees dit weer uit die sessie.
not_found	404	Die hulpbron bestaan nie of behoort aan ’n ander rekening of webwerf. Die API onderskei nooit tussen die twee nie.
conflict	409	Toestandskonflik: optimistiese slot, uniekheidsbeperking, of ’n aksie wat nie in die huidige toestand toegelaat word nie (byvoorbeeld om na ’n saamgevoegde gesprek te skryf).
idempotency_key_conflict	409	Die Idempotency-Key is met ’n ander liggaam hergebruik.
payload_too_large	413	Die liggaam oorskry die limiet vir hierdie eindpuntfamilie.
unsupported_media_type	415	Verkeerde Content-Type.
unprocessable	422	Geldige JSON, maar ’n besigheidsreël het dit geweier (byvoorbeeld ’n besprekingsgleuf buite werksure).
storage_quota_exceeded	422	Die rekening het sy plan se bergingslimiet bereik. details dra used_bytes, quota_bytes en requested_bytes; maak spasie vry of gradeer op.
rate_limited	429	Stadiger. Eerbiedig Retry-After en details.retry_after_seconds.

Bedienerfoute

Kode	Status	Betekenis en wat om te doen
internal_error	500	Onverwagte mislukking. Probeer een keer weer, en kontak dan ondersteuning met request_id.
upstream_unavailable	502	Die poort kon glad nie die diens bereik nie. ’n Kort herprobeer slaag gewoonlik.
service_unavailable	503	Beplande instandhouding of ’n oop stroombreker. Probeer weer ná die Retry-After-opskrif.
ai_vendor_out_of_funds	503	Jou KI-verskaffer het die oproep weens faktureringsredes geweier (’n 402 of ’n kwota-429 van die verskaffer). Laai die verskafferrekening aan; ’n herprobeer sal nie help nie.
upstream_timeout	504	Die diens het nie betyds geantwoord nie. Probeer weer wanneer retry_after teenwoordig is.

Herprobeer

Herprobeer 429, 502, 503, 504 en netwerkmislukkings met eksponensiële terugval, en stuur dieselfde Idempotency-Key by die herprobeer sodat ’n skryfbewerking nooit twee keer toegepas word nie. Moenie 4xx behalwe 429 herprobeer nie.