Erori

Erorile au aceeași structură (vezi prezentarea generală). Construiește logica pe baza code, înregistrează meta.request_id și tratează message ca text în engleză destinat oamenilor.

Erori de client

Cod	Status	Semnificație și ce trebuie făcut
validation_failed	400	Un câmp nu a trecut validarea. field îl numește; details explică. Corectează câmpul.
bad_request	400	Cererea nu a putut fi citită deloc: JSON invalid, un flux Content-Encoding corupt, un corp întrerupt. Nu există un câmp de corectat; verifică transportul.
validation_error	400	X-Account-Id a fost trimis unui endpoint care îl interzice (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Cursorul de paginare este mai vechi de 24 de ore. Reia listarea de la început.
unauthenticated	401	Token lipsă sau invalid. Reîmprospătează sesiunea sau verifică cheia.
invalid_signature	401	Semnătura unui webhook nu a putut fi verificată. Vezi Webhook-uri.
forbidden	403	Tokenul este valid, dar nu are permisiunea necesară.
account_context_mismatch	403	X-Account-Id nu corespunde contului din token. Informația clientului despre compania curentă s-a desincronizat; recitește-o din sesiune.
not_found	404	Resursa nu există sau aparține altui cont ori altui site. API-ul nu face niciodată distincția între cele două.
conflict	409	Conflict de stare: blocare optimistă, constrângere de unicitate sau o acțiune nepermisă în starea curentă (de exemplu scrierea într-o conversație comasată).
idempotency_key_conflict	409	Idempotency-Key a fost refolosită cu un corp diferit.
payload_too_large	413	Corpul depășește limita pentru această familie de endpointuri.
unsupported_media_type	415	Content-Type greșit.
unprocessable	422	JSON valid, dar refuzat de o regulă de business (de exemplu un interval de programare în afara programului de lucru).
storage_quota_exceeded	422	Contul a atins limita de stocare a planului. details conține used_bytes, quota_bytes și requested_bytes; eliberează spațiu sau treci la un plan superior.
rate_limited	429	Încetinește. Respectă Retry-After și details.retry_after_seconds.

Erori de server

Cod	Status	Semnificație și ce trebuie făcut
internal_error	500	Eroare neașteptată. Reîncearcă o dată, apoi contactează suportul cu request_id.
upstream_unavailable	502	Gateway-ul nu a putut contacta deloc serviciul. O reîncercare scurtă reușește de obicei.
service_unavailable	503	Mentenanță planificată sau un circuit breaker deschis. Reîncearcă după intervalul din antetul Retry-After.
ai_vendor_out_of_funds	503	Furnizorul tău de AI a refuzat apelul din motive de facturare (un 402 sau un 429 de cotă de la furnizor). Alimentează contul la furnizor; o reîncercare nu va ajuta.
upstream_timeout	504	Serviciul nu a răspuns la timp. Reîncearcă atunci când este prezent retry_after.

Reîncercări

Reîncearcă 429, 502, 503, 504 și eșecurile de rețea cu backoff exponențial și trimite aceeași Idempotency-Key la reîncercare, pentru ca o scriere să nu fie aplicată niciodată de două ori. Nu reîncerca alte erori 4xx decât 429.