Ошибки

Все ошибки используют один конверт (см. обзор). Ветвите логику по 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.