Ошибки

HTTP-статус показывает класс проблемы, а JSON в теле ответа говорит, что именно не так и, если дело в одном поле, в каком.

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "consent: must be true: confirm the guest agreed to data processing",
    "param": "consent"
  },
  "request_id": "req_0d4d15b86c484738b46b"
}

error.typestring: Общий класс ошибки: invalid_request_error, authentication_error, permission_error, idempotency_error, rate_limit_error, api_error.
error.codestring: Стабильный машиночитаемый код, например member_not_found. Стройте логику на нём, а не на тексте сообщения.
error.messagestring: Пояснение для разработчика. Текст может меняться, не разбирайте его программно.
error.paramstring: Поле запроса, к которому относится ошибка, если оно есть.
request_idstring: Также приходит в заголовке X-Request-Id каждого ответа. Указывайте его, когда пишете нам.

Параметр	Тип	Описание
error.type	string	Общий класс ошибки: `invalid_request_error`, `authentication_error`, `permission_error`, `idempotency_error`, `rate_limit_error`, `api_error`.
error.code	string	Стабильный машиночитаемый код, например `member_not_found`. Стройте логику на нём, а не на тексте сообщения.
error.message	string	Пояснение для разработчика. Текст может меняться, не разбирайте его программно.
error.param	string	Поле запроса, к которому относится ошибка, если оно есть.
request_id	string	Также приходит в заголовке `X-Request-Id` каждого ответа. Указывайте его, когда пишете нам.

HTTP-статусы

Статус	Значение	Что делать
200, 201	Успех. 201 означает, что создан новый объект.
400	Запрос составлен неверно или поле содержит недопустимое значение.	Исправьте запрос. Повтор с тем же телом даст тот же ответ.
401	Ключа нет, он неизвестен или отозван.	Проверьте ключ.
402	Запрос корректен, но выполнить его нельзя, например не хватает баланса.	Покажите гостю сообщение, подробности есть в теле ответа.
403	У ключа нет права, нужного для этого запроса.	Используйте ключ с правом, указанным в сообщении.
404	Участника, транзакции, блюда или заказа нет в этом заведении.	Проверьте идентификатор.
409	Конфликт: номер карты занят, переход статуса недопустим или баланс изменился во время запроса.	Посмотрите код ошибки. При `balance_conflict` повторите запрос с тем же `external_id`.
429	Слишком много запросов.	Подождите столько секунд, сколько указано в `Retry-After`.
500, 502, 503	Сбой на нашей стороне.	Повторите запрос с нарастающей паузой и тем же `external_id` или `Idempotency-Key`. Повторно ничего не применится.

Частые коды

Код	Когда возникает
parameter_invalid	Поле не передано или имеет неверный формат. Смотрите `param`.
member_not_found	Нет участника с таким номером карты, штрихкодом, телефоном или id.
card_number_taken	Этот номер карты уже есть у другого участника заведения.
insufficient_balance	`redeem_amount` больше баланса кэшбэка. Баланс указан в `available`.
redeem_not_supported	В программе участника нет баланса кэшбэка, который можно списать.
visit_not_supported	Визит передан для программы с кэшбэком. Вместо него передайте чек с суммой.
no_reward_available	У участника нет заработанной награды.
transaction_not_found	Нет транзакции с таким `external_id`.
invalid_status_transition	Заказ нельзя перевести из текущего статуса в переданный.
missing_scope	У ключа нет нужного права.
hold_required	Заведение списывает кэшбэк только через резерв. Создайте его через `POST /v1/holds`.
hold_expired, hold_captured, hold_released	Резерв больше нельзя использовать. Создайте новый.
register_id_required	Заведение нумерует чеки по кассам, поэтому `register_id` обязателен.
check_too_old	`closed_at` старше, чем принимает заведение.
scan_required	Заведение принимает это только для карты, которую этот ключ недавно отсканировал.
refund_exceeds_check	Возврат больше, чем осталось от чека. Остаток указан в `refundable`.
adjustments_disabled	Заведение не разрешило корректировки баланса через API.
idempotency_key_reused	Тот же `Idempotency-Key` использован с другим телом запроса.
rate_limited	Слишком много запросов с этим ключом.