Коды ошибок

Ошибки приходят как application/problem+json с машинным кодом.

Любая ошибка — статус 4xx/5xx и application/problem+json (RFC 9457) с машинным code и request_id; заголовок Request-Id есть в каждом ответе. Ветвитесь по code, а title и detail показывайте человеку — их текст может уточняться. Все коды — примеры ответов каждой операции и страница https://lazycrm.ru/docs/api/errors.

{
  "type": "https://lazycrm.ru/docs/api/errors#validation_error",
  "code": "validation_error",
  "title": "Поле не прошло проверку",
  "status": 422,
  "detail": "Телефон должен быть в формате +7XXXXXXXXXX, получено «8 900 12».",
  "errors": [
    {
      "field": "phone",
      "code": "invalid_phone"
    }
  ],
  "request_id": "req_8f2c1a9b"
}

Коды ошибок

status	code	Когда	Что делать
400	`idempotency_key_required`	Отправка без заголовка Idempotency-Key	Добавить заголовок (UUID)
400	`invalid_cursor`	Курсор битый или выдан для другого запроса	Начать список заново без cursor
400	`unknown_parameter`	Неизвестный query-параметр или поле тела (в т.ч. tenant_id); имя — в errors[].field	Убрать параметр
401	`channel_key_expired`	Checkout boundary returned channel_key_expired	Inspect the scoped channel and original operation receipt before retrying.
401	`invalid_api_key`	Ключ неизвестен или отозван	Выпустить новый в кабинете
401	`missing_api_key`	Нет заголовка Authorization	Передать ключ
403	`channel_grant_required`	Checkout boundary returned channel_grant_required	Inspect the scoped channel and original operation receipt before retrying.
403	`channel_scope_mismatch`	Checkout boundary returned channel_scope_mismatch	Inspect the scoped channel and original operation receipt before retrying.
403	`insufficient_scope`	У ключа нет нужного права; detail называет его	Выпустить ключ с полным доступом
403	`paid_feature_required`	GET /v1/guests без платной опции «Выгрузка базы по API»	Подключить опцию у менеджера или искать гостя через /v1/guests/lookup
403	`server_channel_required`	Checkout boundary returned server_channel_required	Inspect the scoped channel and original operation receipt before retrying.
404	`not_found`	Объекта нет или он другого ресторана	Проверить id
409	`campaign_already_sent`	Отправка рассылки не в draft с новым ключом повтора	Прочитать статус GET /v1/campaigns/{campaign_id}
409	`campaign_not_cancelable`	Отправка уже началась, закончилась или рассылка не запланирована	Ничего — рассылку уже не отменить
409	`empty_audience`	На момент отправки получателей 0	Выбрать другой сегмент
409	`idempotency_conflict`	Checkout boundary returned idempotency_conflict	Inspect the scoped channel and original operation receipt before retrying.
409	`idempotency_request_in_progress`	Первый запрос с этим ключом повтора ещё выполняется	Повторить через секунду
409	`loyalty_conflict`	Checkout boundary returned loyalty_conflict	Inspect the scoped channel and original operation receipt before retrying.
422	`idempotency_key_reused`	Тот же ключ повтора с другим запросом	Новый ключ на новый запрос
422	`validation_error`	Значение не прошло проверку; причины в errors[]: unknown_segment, text_empty, text_too_long, scheduled_at_in_past, invalid_phone, invalid_datetime, out_of_range, required	Исправить поле из errors[].field
429	`rate_limited`	Больше 600 запросов в минуту на ключ; Retry-After	Подождать Retry-After секунд
429	`send_limit_reached`	20 отправок за сутки уже было; Retry-After до полуночи ресторана	Отправить завтра
500	`internal_error`	Ошибка на нашей стороне	Повторить запрос; не проходит — написать в поддержку с request_id
503	`sending_disabled`	Отправка SMS на платформе временно выключена; Retry-After	Повторить позже тем же ключом повтора
503	`upstream_unavailable`	Сервис или SMS-шлюз временно недоступен; Retry-After	Повторить позже