Помилки

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` кожної відповіді. Вказуйте його, коли пишете нам.

Коди статусу

Статус	Значення	Що робити
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	Забагато запитів із цього ключа.