Klaidos

Klaidos turi vieną apvalkalą (žr. apžvalgą). Logiką šakokite pagal code, registruokite meta.request_id, o message laikykite anglišku tekstu žmonėms.

Kliento klaidos

Kodas	Būsena	Reikšmė ir ką daryti
validation_failed	400	Laukas nepraėjo patikrinimo. field jį nurodo; details paaiškina. Pataisykite lauką.
bad_request	400	Užklausos visai nepavyko perskaityti: netinkamas JSON, sugadintas Content-Encoding srautas, nutrauktas turinys. Taisyti nėra ko lauke; patikrinkite perdavimą.
validation_error	400	X-Account-Id išsiųsta į galinį tašką, kuris jos draudžia (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Puslapiavimo žymeklis senesnis nei 24 valandos. Pradėkite sąrašą iš naujo.
unauthenticated	401	Trūksta žetono arba jis netinkamas. Atnaujinkite sesiją arba patikrinkite raktą.
invalid_signature	401	Webhook’o parašas nepraėjo patikrinimo. Žr. Webhook’ai.
forbidden	403	Žetonas galioja, bet neturi leidimo.
account_context_mismatch	403	X-Account-Id nesutampa su žetono paskyra. Kliento supratimas apie dabartinę įmonę nukrypo; perskaitykite jį iš sesijos iš naujo.
not_found	404	Išteklius neegzistuoja arba priklauso kitai paskyrai ar svetainei. API niekada šių atvejų neskiria.
conflict	409	Būsenos konfliktas: optimistinis užraktas, unikalumo apribojimas arba veiksmas, neleidžiamas dabartinėje būsenoje (pavyzdžiui, rašymas į sujungtą pokalbį).
idempotency_key_conflict	409	Idempotency-Key pakartotinai panaudotas su kitu turiniu.
payload_too_large	413	Turinys viršija šios galinių taškų šeimos limitą.
unsupported_media_type	415	Netinkamas Content-Type.
unprocessable	422	JSON tinkamas, bet verslo taisyklė jį atmetė (pavyzdžiui, rezervacijos laikas už darbo valandų).
storage_quota_exceeded	422	Paskyra pasiekė savo plano saugyklos limitą. details pateikia used_bytes, quota_bytes ir requested_bytes; atlaisvinkite vietos arba pasirinkite aukštesnį planą.
rate_limited	429	Sulėtinkite. Paisykite Retry-After ir details.retry_after_seconds.

Serverio klaidos

Kodas	Būsena	Reikšmė ir ką daryti
internal_error	500	Netikėta klaida. Pakartokite vieną kartą, tada susisiekite su palaikymo komanda, nurodydami request_id.
upstream_unavailable	502	Šliuzas visai negalėjo pasiekti tarnybos. Trumpas pakartojimas paprastai pavyksta.
service_unavailable	503	Planuota techninė priežiūra arba suveikęs grandinės pertraukiklis. Pakartokite po laiko, nurodyto antraštėje Retry-After.
ai_vendor_out_of_funds	503	Jūsų AI tiekėjas atmetė iškvietimą dėl atsiskaitymo priežasčių (tiekėjo 402 arba kvotos 429). Papildykite tiekėjo paskyrą; pakartojimas nepadės.
upstream_timeout	504	Tarnyba neatsakė laiku. Pakartokite, kai yra retry_after.

Pakartojimai

Kartokite 429, 502, 503, 504 ir tinklo klaidas su eksponentiškai didėjančiu intervalu ir pakartojime siųskite tą patį Idempotency-Key, kad rašymas niekada nebūtų pritaikytas du kartus. Nekartokite 4xx, išskyrus 429.