Помилки

Усі помилки мають один конверт (див. огляд). Розгалужуйте логіку за 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	Ваш ШІ-провайдер відхилив виклик із причин оплати (402 або 429 через квоту від постачальника). Поповніть рахунок у постачальника; повтор не допоможе.
upstream_timeout	504	Сервіс не відповів вчасно. Повторіть, якщо є retry_after.

Повторні спроби

Повторюйте 429, 502, 503, 504 і мережеві збої з експоненційною затримкою та надсилайте під час повтору той самий Idempotency-Key, щоб запис ніколи не застосувався двічі. Не повторюйте 4xx, крім 429.