Қателер

Барлық қателердің конверті бірдей (шолуды қараңыз). Логиканы code бойынша тармақтаңыз, meta.request_id мәнін логқа жазыңыз, ал message өрісін адамдарға арналған ағылшынша мәтін деп есептеңіз.

Клиент қателері

Код	Күй	Мағынасы және не істеу керек
validation_failed	400	Өріс тексеруден өтпеді. field оны атайды, details себебін түсіндіреді. Өрісті түзетіңіз.
bad_request	400	Сұрауды мүлде оқу мүмкін болмады: жарамсыз JSON, бүлінген Content-Encoding ағыны, үзілген дене. Түзетілетін өріс жоқ; тасымалдауды тексеріңіз.
validation_error	400	X-Account-Id оған тыйым салатын эндпоинтке жіберілді (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	Беттеу курсоры 24 сағаттан ескі. Тізімді басынан бастаңыз.
unauthenticated	401	Токен жоқ немесе жарамсыз. Сессияны жаңартыңыз немесе кілтті тексеріңіз.
invalid_signature	401	Вебхук қолтаңбасы расталмады. Вебхуктарды қараңыз.
forbidden	403	Токен жарамды, бірақ рұқсаты жоқ.
account_context_mismatch	403	X-Account-Id токеннің аккаунтына сәйкес келмейді. Клиенттің ағымдағы компания туралы түсінігі ауытқыған; оны сессиядан қайта оқыңыз.
not_found	404	Ресурс жоқ немесе басқа аккаунтқа не сайтқа тиесілі. API бұл екеуін ешқашан ажыратпайды.
conflict	409	Күй қайшылығы: оптимистік бұғаттау, бірегейлік шектеуі немесе ағымдағы күйде рұқсат етілмеген әрекет (мысалы, біріктірілген сұхбатқа жазу).
idempotency_key_conflict	409	Idempotency-Key басқа денемен қайта пайдаланылды.
payload_too_large	413	Дене осы эндпоинттер тобының лимитінен асып кетті.
unsupported_media_type	415	Content-Type қате.
unprocessable	422	JSON жарамды, бірақ бизнес-ереже оны қабылдамады (мысалы, жұмыс уақытынан тыс брондау слоты).
storage_quota_exceeded	422	Аккаунт жоспарының сақтау лимитіне жетті. details ішінде used_bytes, quota_bytes және requested_bytes бар; орын босатыңыз немесе жоғарырақ жоспарға өтіңіз.
rate_limited	429	Сұрау жиілігін азайтыңыз. Retry-After пен details.retry_after_seconds мәндерін сақтаңыз.

Сервер қателері

Код	Күй	Мағынасы және не істеу керек
internal_error	500	Күтпеген ақау. Бір рет қайталаңыз, содан кейін request_id арқылы қолдау қызметіне хабарласыңыз.
upstream_unavailable	502	Шлюз сервиске мүлде жете алмады. Қысқа қайталау әдетте сәтті болады.
service_unavailable	503	Жоспарлы техникалық қызмет немесе ашық сақтандырғыш (circuit breaker). Retry-After тақырыбындағы уақыттан кейін қайталаңыз.
ai_vendor_out_of_funds	503	AI провайдеріңіз шақыруды төлем себептерімен қабылдамады (жеткізушіден 402 немесе квота бойынша 429). Жеткізушідегі шотты толықтырыңыз; қайталау көмектеспейді.
upstream_timeout	504	Сервис уақытында жауап бермеді. retry_after болса, қайталаңыз.

Қайталау

429, 502, 503, 504 және желі ақауларын экспоненциалды кідіріспен қайталаңыз және жазба ешқашан екі рет қолданылмауы үшін қайталағанда сол Idempotency-Key мәнін жіберіңіз. 429-дан басқа 4xx кодтарын қайталамаңыз.