Грешки

Грешките споделят една обвивка (вижте общия преглед). Разклонявайте логиката по 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.