Коди помилок

Тіло помилки завжди однакове. Орієнтуйтеся на code, а не на текст: текст написано для людини, і він може змінюватися.

JSON

{ "error": { "code": "duplicate_order", "message": "Рахунок для цього order_id уже створено" } }

Коли повторювати безпечноУ разі 429, 500, 503, idempotency_in_progress і мережевих помилок — з тим самим Idempotency-Key: дубліката не буде.

Запит і доступ

HTTP	code	Причина та що робити
400	`bad_json`, `bad_body`	Тіло не JSON, зайві поля або сума числом замість рядка — виправте запит
400	`bad_idempotency_key`	Немає ключа або неправильний формат: 8–128 друкованих символів ASCII, не починається з `d:`
400	`bad_query`	Неправильні параметри списку
401	`unauthorized`	Підпис, час, nonce або ключ — див. CP-HMAC
403	`merchant_suspended`	Мерчанта призупинено — зверніться до підтримки
403	`merchant_not_approved`	Підключення не завершено або заявка на розгляді — завершіть майстер у кабінеті
403	`billing_suspended`	Не оплачено рахунок на комісію — оплатіть у кабінеті, розділ «Білінг»; призупинення знімається одразу
404	`not_found`	Рахунку немає або він чужий
413	`body_too_large`	Тіло перевищує ліміт — зменште `metadata`
429	`rate_limited`	Забагато запитів — повторіть з експоненційною паузою
500	`internal`	Внутрішня помилка — повторіть з тим самим `Idempotency-Key`

Рахунки та ідемпотентність

HTTP	code	Причина та що робити
409	`duplicate_order`	`order_id` уже використано — потрібен новий, наприклад `ORDER-1001-2`
409	`idempotency_conflict`	Той самий ключ з іншим тілом
409	`idempotency_in_progress`	Перший запит ще виконується — повторіть за 1–2 с
409	`invoice_not_payable`	Рахунок прострочено або закрито — створіть новий
422	`invalid_order_id`, `invalid_price_amount`, `invalid_price_currency`, `invalid_return_url`, `invalid_expires_in_seconds`, `invalid_metadata`	Поле не пройшло перевірку — текст підказує правило
422	`invalid_allowed_assets`	Жоден актив зі списку не доступний — у тексті причина для кожного
422	`no_assets`	Немає жодного доступного активу — перевірте гаманці й активи в кабінеті
422	`amount_too_small`	Сума менша за мінімум усіх доступних активів

Вибір валюти на сторінці оплати

Ці помилки обробляє сторінка оплати — ваш сервер стикається з ними, лише якщо ви викликаєте select самі.

HTTP	code	Причина
409	`asset_locked`	Зміна валюти після платежу
409	`wallet_not_configured`	Немає чинного гаманця для приймання в цій мережі
409	`wallet_changed`, `address_conflict`	Повторіть вибір
422	`asset_not_allowed`	Активу немає в рахунку або він більше не дозволений
503	`rate_unavailable`	Немає підтвердженого курсу — запропонуйте стейблкоїн
503	`network_unavailable`	Приймання в мережі тимчасово недоступне — оберіть іншу

Повернення

HTTP	code	Причина
403	`merchant_inactive`	Магазин призупинено або ключ відкликано
409	`invoice_not_paid`	Для рахунку не обрано актив — повертати нічого
409	`nothing_to_refund`	Усе вже повернуто або запитано
409	`too_many_refunds`	20 відкритих заявок за рахунком
409	`refund_executor`	Повернення виконує платформа, а не ви
409	`invoice_status_changed`	Статус рахунку змінився після заявки — повторіть з `"ack_status_change": true`
422	`amount_exceeds_refundable`	Сума більша за доступну — зменште її або вкажіть `"full"`
422	`invalid_amount`, `invalid_address`, `invalid_tx_hash`	Поле не пройшло перевірку