Грешки

Грешките делат една обвивка (погледнете го прегледот). Разгранувајте ја логиката според 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 при повторниот обид, за запишувањето никогаш да не се примени двапати. Не повторувајте 4xx освен 429.