Ніколи не повторювати
invalid_request, invalid_amount, unknown_asset_or_rail, asset_not_offered, unauthorized. Помилка в запиті: повторення його без змін дає той самий результат. Виправте його або покажіть причину.
Developers
Каталог помилок
Кожна помилка несе стабільний, машиночитаний код і узгоджений статус HTTP. Код — це те, на що має спиратися ваша інтеграція: текст може змінюватися, код — ні.
Форма помилки
Поточна форма навмисно мінімальна. Вона стабільна, і це головне: код і нічого, що витікає внутрішні деталі.
{ "error": "rate_stale" }{
"error": "rail_not_open",
"reason": {
"fr": "La retenue TDS de 1 % et l’enregistrement FIU-IND exigent une entite locale…",
"en": "The 1% TDS withholding and FIU-IND registration require a local entity…"
}
}Деякі помилки несуть двомовний об'єкт причини, призначений для показу як є користувачу. Закритий платіжний канал — один із таких: причина пояснює назване регуляторне обмеження, а не збій, і її показ економить звернення до підтримки. Версіонований API додасть ідентифікатор запиту до цього конверта, щоб ви могли вказати нам на точний рядок у наших журналах.
Чинні коди
Ці коди повертаються сьогодні кінцевою точкою котирування.
| code | HTTP | Що це означає | Що робити |
|---|---|---|---|
invalid_request | 400 | Тіло запиту не проходить валідацію схеми: відсутнє поле, неправильний тип, значення поза допустимими межами. | Перевірте, що сума є рядком, а не числом, і що напрямок точно «sell» або «receive». |
invalid_amount | 400 | Суму неможливо розібрати, або вона містить більше десяткових знаків, ніж приймає актив або валюта. | Округліть до точності одиниці: 6 десяткових знаків для USDT, 8 для BTC, 2 для євро, 0 для франка КФА. |
unknown_asset_or_rail | 404 | Ідентифікатор активу або каналу не існує в каталозі. | Ідентифікатори стабільні й ніколи не переназначаються. Перезавантажте каталог, а не вгадуйте їх. |
rail_not_open | 409 | Канал існує, але не відкритий. Відповідь містить точну причину обома мовами. | Покажіть причину як є: вона пояснює регуляторне обмеження, а не збій. Запропонуйте відкритий канал у тій самій країні. |
asset_not_offered | 409 | Актив є в каталозі, але не пропонується — випадок активів із підвищеною анонімністю. | Не пропонуйте його у своєму селекторі. Каталог повертає його з причиною, щоб ви могли її пояснити. |
rate_stale | 503 | Остання відома ціна перевищує максимально допустимий вік. Механізм відмовляється цитувати, а не подає застарілу ціну як тверду. | Повторіть спробу через кілька секунд. Не кешуйте останню успішну цитату, щоб заповнити прогалину: це була б саме та помилка, яку цей код запобігає. |
rate_unavailable | 503 | Немає доступної ціни для цієї пари актив/валюта. | Вимкніть пару у своєму інтерфейсі, а не показуйте оцінку. Показана оцінка стає очікуванням. |
quote_failed | 500 | Неочікувана помилка під час обчислення. Жодна цитата не повертається. | Повторіть один раз; якщо помилка повторюється, напишіть нам із точним часом виклику. |
Коди з опублікованого контракту
Ці коди супроводжують кінцеві точки, які ще не відкриті. Вони опубліковані, щоб ваша обробка помилок була написана один раз.
| code | HTTP | Що це означає | Що робити |
|---|---|---|---|
unauthorized | 401 | Ключ відсутній, відкликаний або використаний у неправильному середовищі. | Ключ sk_test_ не працює в продакшені, і навпаки — це навмисно. |
idempotency_conflict | 409 | Той самий ключ ідемпотентності вже було використано з іншим тілом запиту. | Ключ належить одному наміру. Якщо вміст змінюється, ключ змінюється; інакше неможливо визначити, яке з двох замовлень відтворювати. |
quote_expired | 409 | Котирування вийшло за межі свого вікна фіксації. | Запропонуйте нову котирування та отримайте підтвердження нової суми. Ми ніколи не змінюємо ціну мовчки проти клієнта. |
beneficiary_rejected | 422 | Дані бенефіціара не проходять перевірку платіжної системи: недійсна контрольна сума, невідповідний формат або ім'я, яке не збігається з підтвердженою особою. | У відповіді вказано поле, що викликає проблему. Ім'я бенефіціара має бути підтвердженою особою: виплата третім особам неможлива. |
country_not_served | 451 | Країна призначення не обслуговується: санкції, обмежувальні заходи або відсутність місцевої правової бази. | Код 451 обрано навмисно, а не 404: коли ми відмовляємо, ми говоримо, що це відмова і чому. |
rate_limited | 429 | Забагато викликів у межах ковзного вікна. | Дотримуйтесь заголовка Retry-After. Котирування дешево ставити в чергу, дорого — атакувати. |
not_found | 404 | Ресурс не існує або не належить вашому ключу. | Обидва випадки повертають однаковий код: відповідь, яка їх розрізняє, дозволила б будь-кому перелічувати чужі посилання. |
Що не є помилкою
Сума поза межами каналу повертає дійсне котирування з об'єктом limitError. Це не збій: це інформація, яку ваш інтерфейс має відображати.
"limitError": { "code": "below_min", "limit": "20.00" }Розгляд цього випадку як помилки HTTP позбавив би вас обчисленої суми, а отже, і можливості сказати користувачу: «вам бракує 16.53 EUR до мінімуму для цього методу виплати». Обмеження застосовується до чистої суми, тієї, яку отримує бенефіціар.
Повторювати чи ні
Три родини, три поведінки. Повторення помилки валідації в циклі лише заповнює ваші журнали.
Повторювати з відступом
rate_stale, rate_unavailable, quote_failed та будь-яке обмеження швидкості. Зачекайте кілька секунд, зі збільшенням проміжку між спробами. Не заповнюйте проміжок кешованим котируванням.
Запитайте рішення
rail_not_open, quote_expired, beneficiary_rejected, country_not_served. Ситуація потребує вибору людини: запропонуйте інший канал, свіже котирування, виправлені деталі.