Ідемпотентність, помилки та ліміти
Якщо запит завершився таймаутом, ви не знаєте, чи він виконався. Повторіть ту саму операцію з тим самим Idempotency-Key, щоб не створити другий платіж.
Один ключ на дію
Section titled “Один ключ на дію”- Згенеруйте унікальний ключ перед першим запитом і збережіть його разом із замовленням.
- Надішліть його в
Idempotency-Keyпід час створення або зміни бізнес-ресурсу. - Після таймауту повторіть той самий метод, шлях і тіло з цим ключем.
- Для нової дії створіть новий ключ.
Ключ має бути непорожнім і не довшим за 128 байт. Повторення завершеної дії повертає збережену відповідь. Зміна тіла під тим самим ключем повертає 409 idempotency_conflict.
Це стосується бізнес-мутацій, як-от рахунки, магазини, ключі та вебхуки. Запити GET лише для читання і виклики входу цей механізм не використовують. Дотримуйтеся вимог кожного ендпоінту.
external_id допомагає пов’язати платіж із вашим замовленням; це не ключ ідемпотентності.
Читання помилок за кодом
Section titled “Читання помилок за кодом”Приклад:
{"error":{"code":"idempotency_conflict","message":"idempotency_conflict"}}Використовуйте error.code у своїй програмі. Не робіть висновок про успіх із тіла відповіді без попередньої перевірки HTTP-статусу.
| Код | Наступна дія |
|---|---|
unauthorized |
Перевірте облікові дані, права та будь-яке обмеження за IP. Увійдіть знову, якщо сесія закінчилася. |
mfa_required |
Пройдіть другий фактор облікового запису, використовуючи його сесію. |
onboarding_required |
Завершіть /onboarding, перш ніж працювати з магазином. |
idempotency_key_required |
Надайте збережений непорожній ключ, не більше 128 байт. |
idempotency_conflict |
Знайдіть початковий запит. Не створюйте мовчки новий платіж. |
json_content_type_required / invalid_json |
Надсилайте Content-Type: application/json і лише задокументовані поля. |
unsupported_network / unsupported_asset |
Оберіть підтримувану мережу й токен. |
network_not_ready / asset_not_ready |
Дочекайтеся доступності або оберіть інший готовий маршрут. |
address_unavailable |
503: адресу зараз не вдалося отримати. Повторіть той самий запит із тим самим Idempotency-Key. |
amount_below_minimum / fee_exceeds_amount |
Перевірте суму, кількість знаків після коми та умови магазину. |
shop_archived / shop_not_found |
Перевірте магазин і доступ. |
invalid_expires_in |
Надсилайте 1h, 2h, 1d, 7d, 30d, 180d або 365d, і лише під час створення рахунку. Депозити не мають терміну дії. |
invalid_assets / issuance_in_group |
Надсилайте окремі пари {chain_id, token} без chain_id і token; скасовуйте або призупиняйте групу за її власним id. Див. кілька токенів або мереж. |
solana_setup_required / tron_setup_required |
Спершу задайте отримувача Solana або Tron для магазину. |
invoice_amount_limit / sandbox_amount_limit |
Зменшіть суму в межах ліміту. |
active_invoice_limit_reached / deposit_address_limit_reached |
Скасуйте непотрібні рахунки або вимкніть непотрібні депозити, або попросіть Invoise підняти ліміт. |
api_key_limit_reached / too_many_allowed_ips / webhook_limit_reached |
Відкличте невикористовувані ключі, скоротіть список IP або повторно використайте наявний ендпоінт. |
team_limit_reached |
Видаліть учасника або відкличте запрошення, що очікує, або попросіть Invoise підняти ліміт. |
shop_limit_reached |
Архівуйте магазин, який більше не потрібен, або попросіть Invoise підняти ліміт. |
own_merchant / last_merchant_owner / wallet_in_use |
Не можна вийти з мерчанта, який ви створили, або якщо ви його останній власник; спершу переведіть виплати перелічених магазинів з вашого гаманця. |
account_disabled |
Персонал Invoise заблокував обліковий запис; причина — в error.details. Див. заблоковані облікові записи. |
rate_limited |
Дочекайтеся кількості секунд із Retry-After, перш ніж повторити. |
Ліміти
Section titled “Ліміти”Коли запит перевищив би ліміт, Invoise відхиляє його зі звичним тілом помилки й кодом нижче.
| Ліміт | Значення | Помилка |
|---|---|---|
| Сума одного рахунку | 1 000 000 токенів за замовчуванням | 400 invoice_amount_limit |
| Сума одного рахунку пісочниці або симульованого переказу | 10 000 токенів | 400 sandbox_amount_limit |
| Активних рахунків на мерчанта | 2000 | 400 active_invoice_limit_reached |
| Активних депозитних адрес на мерчанта, на родину мереж | EVM 100 000, Tron 100 000, Solana 100 | 400 deposit_address_limit_reached |
| Нові адреси для оплати на мерчанта за годину: рахунки, депозити й кожен їхній варіант | ліміт активних рахунків мерчанта, за замовчуванням 2000 | 429 rate_limited |
| Активних магазинів на мерчанта | 10 | 400 shop_limit_reached |
| Невідкликаних API-ключів на магазин | 10 | 400 api_key_limit_reached |
| Дозволених IP-адрес або діапазонів CIDR на ключ | 10 | 400 too_many_allowed_ips |
| Ендпоінтів вебхуків на магазин | 10 | 400 webhook_limit_reached |
| Учасників команди та очікуваних запрошень на мерчанта | 10 | 400 team_limit_reached |
| Запитів за хвилину | 1200 на ключ або сесію, з яких не більше 120 не GET; 3000 і 300 на IP клієнта | 429 rate_limited |
Ліміти сум — у цілих токенах, не в базових одиницях. Кожен підтримуваний токен — доларовий стейблкоїн, тож 1 000 000 токенів — це близько $1 000 000.
Рахунок активний, поки його не оплачено, не скасовано або не минув термін. Рахунок, запропонований у кількох мережах, рахується один раз. Депозитна адреса активна, поки її не вимкнено; кожен мережевий варіант депозиту — окрема адреса. Пісочниця й продакшен рахуються окремо для обох лімітів. Архівований магазин не займає місця в ліміті магазинів.
У таблиці наведено значення за замовчуванням. Персонал Invoise може встановити мерчанту інші ліміти рахунків, депозитних адрес, магазинів і команди, тож ваші можуть відрізнятися, а граничну суму рахунку — змінити для всіх мерчантів.
Ліміт команди застосовується і при запрошенні, і при прийнятті запрошення. URL ендпоінту вебхука можна змінити, тож можна повторно використати ендпоінт замість додавання нового.
Запити рахуються на API-ключ або сесію кабінету й завжди ще на IP клієнта, тож вигаданий ключ не починає лік заново.
Кожна відповідь 429 містить Retry-After — скільки секунд чекати. Для похвилинного ліміту запитів це 60. Погодинні ліміти, як-от бюджет нових адрес, коди входу на email і запити входу через гаманець, називають кількість секунд до відкриття вікна — до години.
Повторюйте без дублікатів
Section titled “Повторюйте без дублікатів”Повторюйте таймаути й тимчасові помилки сервера з тим самим ключем, зі зростаючими затримками. При 429 дочекайтеся кількості секунд із Retry-After (для бюджету нових адрес — до години); не надсилайте нові запити одразу. Виправте неправильні вхідні дані й помилки доступу, перш ніж повторювати.
Для вебхуків Invoise повторює доставку протягом 72 годин; див. Повтори. Приймайте подію надійно, повертайте 2xx, потім обробляйте її. Усувайте дублікати за Invoise-Event-ID.
Старіші маршрути /projects — це псевдоніми /shops, зокрема їхня область ідемпотентності. Для нових інтеграцій використовуйте /shops. У застарілих назвах помилок може вживатися project_*.