Обробка помилок

Кожен неуспішний запит до API повертає JSON з уніфікованою структурою помилки. Цей гайд описує її поля, перелік типів та приклади типових збоїв.

Структура відповіді з помилкою

{
  "code": "invalid_card_data",
  "error_id": "err_a3f2c1d4-5b6e-4e9a-b8f0-2c9d1e7f8a3b",
  "type": "payment_method_error",
  "param": "customer.payment_method.cc.number",
  "message": "Card number is invalid"
}

Поле	Тип	Опис
`code`	string	Машинний код помилки — див. Статуси та коди
`error_id`	string	Унікальний ID події. Передавайте в підтримку при зверненні
`type`	string	Категорія помилки (enum, див. нижче)
`param`	string	Поле запиту, що спричинило помилку (dot-notation)
`message`	string	Текстовий опис для розробника. Не показуйте користувачу — використовуйте локалізовані тексти за `code`

Типи помилок (`type`)

Тип	Коли виникає	Дія
`invalid_request_error`	Некоректний формат або відсутні обов’язкові поля	Виправте запит, не повторюйте його
`payment_method_error`	Проблема з карткою/токеном/гаманцем (відмова банку, CVV, строк дії)	Попросіть іншу картку
`payment_settings_error`	Налаштування мерчанта не дозволяють операцію (3DS off, preauth off, валюта)	Зверніться до підтримки
`payment_error`	Помилка на рівні платежу — дублікат, скасовано платником, ліміт	Залежить від `code`
`api_error`	Внутрішня помилка шлюзу	Повторіть із тим самим `external_id`
`customer_error`	Проблема з профілем клієнта чи авторизацією	Перевірте `customer.*` поля

Це повний перелік — type не має інших значень. Хибний URL або метод повертає code: missing_route з типом invalid_request_error.

HTTP-статуси

HTTP	Коли виникає
`400`	`invalid_request_error`, більшість `payment_method_error`
`401`	Невалідні дані авторизації (`authorization_error`)
`403`	`access_error`, `access_not_allowed`, `restricted_ip`
`404`	`missing_route`, `transaction_not_found`, `subscription_not_found`
`409`	`action_already_done`, `transaction_already_paid`
`422`	`payment_settings_error`, бізнес-правила
`5xx`	`api_error`, `internal_error`, `timeout`

Приклади типових збоїв

Невалідні дані запиту

{
  "code": "invalid_request_body",
  "error_id": "err_11111111-2222-3333-4444-555555555555",
  "type": "invalid_request_error",
  "param": "amount",
  "message": "amount must be greater than 0"
}

Некоректна картка

{
  "code": "wrong_card_number",
  "error_id": "err_22222222-3333-4444-5555-666666666666",
  "type": "payment_method_error",
  "param": "customer.payment_method.cc.number",
  "message": "Card number failed Luhn check"
}

Недостатньо коштів

{
  "code": "insufficient_funds",
  "error_id": "err_33333333-4444-5555-6666-777777777777",
  "type": "payment_error",
  "message": "Insufficient funds on card"
}

Дубль external_id

{
  "code": "action_already_done",
  "error_id": "err_44444444-5555-6666-7777-888888888888",
  "type": "payment_error",
  "param": "external_id",
  "message": "Payment with this external_id already exists"
}

Невалідні дані авторизації

{
  "code": "authorization_error",
  "error_id": "err_55555555-6666-7777-8888-999999999999",
  "type": "invalid_request_error",
  "message": "Invalid login or password"
}

Повторні спроби та ідемпотентність

5xx та мережеві таймаути можна повторювати з тим самим external_id — API поверне попередній результат замість створення дубля.
4xx означає помилку в запиті — виправте його перед повторною спробою.
Для платежів у стані pending чекайте на callback або періодично опитуйте GET /api/payments/v1/info.

Логування

Зберігайте мінімум:

error_id — ключ для звернень у підтримку
code та type — для аналітики та алертів
ваш external_id — для зіставлення з замовленням
HTTP-статус і заголовок X-Request-Id, якщо API його повернув

Див. також

Статуси і коди помилок — повний реєстр code
Callbacks / Webhooks — обробка асинхронних статусів