Помилки

Кожна відповідь не з класу 2xx на /v1 має один і той самий конверт. Розгалужуйте логіку за errors[0].code, а не за текстом повідомлення: повідомлення призначені для людей і можуть змінюватися, а коди стабільні.

Конверт помилки

{
  "status": "error",
  "data": null,
  "errors": [
    {
      "code": "IDEMPOTENCY_KEY_CONFLICT",
      "message": "Idempotency-Key was already used with a different request body",
      "parameter": "idempotency-key"
    }
  ]
}

• status завжди "error", а data завжди null.
• errors містить щонайменше один запис. code — одне зі значень таблиці нижче; parameter називає поле чи заголовок, через який виникла помилка, якщо його можна визначити, інакше — null.

Ідентифікатори запитів

Кожна відповідь містить заголовок x-request-id. Якщо ви надішлете коректний x-request-id у запиті, його буде повернуто назад; інакше його згенерують. Записуйте його в журнал разом із кожним викликом і називайте, коли звертаєтеся до підтримки: hello@leeri.ai.

Як реагувати

Ситуація	Що робити
429 з RATE_LIMIT_EXCEEDED або PROVIDER_CAPACITY_EXCEEDED	Зачекайте кількість секунд із заголовка Retry-After, потім повторіть той самий запит. Див. Обмеження частоти запитів і ліміти.
503 з REPORT_RENDERING	Повторіть через інтервал із Retry-After; посилання на звіт залишається чинним.
503 з RULESET_UNAVAILABLE, RATE_LIMIT_STORE_UNAVAILABLE, SERVICE_DRAINING або UPSTREAM_UNAVAILABLE	Retry-After не надсилається. Повторюйте з експоненційною затримкою та випадковим розкидом (jitter). За відхилений запит нічого не стягується.
500 з INTERNAL_ERROR	Повторіть із затримкою й тим самим Idempotency-Key; якщо збій повторюється, напишіть у підтримку з x-request-id.
409 з IDEMPOTENCY_REQUEST_IN_FLIGHT	Перший запит із цим ключем ще виконується. Повторіть той самий запит після короткої паузи. Див. Ідемпотентність.
409 з IDEMPOTENCY_LEASE_LOST	Інший повторний запит перехопив ключ, поки цей виконувався. Надішліть той самий запит ще раз, щоб прочитати записаний результат.
422 з PROVIDER_CAPACITY_REQUEST_TOO_LARGE	Ніколи не повторюйте без змін: запит більший за ємність, яку можна коли-небудь виділити. Розбийте його на менші запити.
402 з INSUFFICIENT_BALANCE	Ліміт і попередньо поповнений баланс вичерпано. Повтор не допоможе, доки баланс не поповнять.
Будь-яка інша 4xx	Помилка в самому запиті (VALIDATION_ERROR, ADDRESS_REQUIRED, UNSUPPORTED_ASSET, NOT_FOUND, SCOPE_ERROR тощо). Виправте його; повтор без змін поверне ту саму помилку.

Запит, що завершився статусом 4xx або 5xx, не записується під його Idempotency-Key, тож повторний запит виконається знову.

Коди помилок

Таблицю згенеровано з контракту API, до якого прив'язана ця документація, тож вона завжди містить рівно ті коди, які може повернути API. Кожен код є ціллю посилання: наприклад, ./errors.mdx#ADDRESS_REQUIRED веде до його рядка.

Код	HTTP-статус	Умова
VALIDATION_ERROR	400	Тіло запиту, параметри або заголовок не пройшли валідацію Zod: невідоме поле, значення поза заявленими межами або структура, яку ендпоінт не може розібрати.
AUTH_ERROR	401	Заголовок Authorization відсутній, має неправильний формат або не відповідає активному ключу API з чинним строком дії.
SCOPE_ERROR	403	Ключ API пройшов автентифікацію, але не має scope, потрібного для цього маршруту.
TENANT_BOUNDARY	403	Читання або запис на рівні даних виявили посилання на дані іншого клієнта (tenant) — це відмова самого захисту RLS на рівні платформи, а не перевірка на рівні маршруту.
NOT_FOUND	404	Ресурсу з таким id немає для автентифікованого клієнта та середовища ключа (live/sandbox). Це стосується й id іншого клієнта або іншого середовища: відповідь свідомо така сама, як для неіснуючого id.
IDEMPOTENCY_KEY_CONFLICT	422	Той самий Idempotency-Key уже використовувався для цього ендпоінта з іншим тілом запиту.
INSUFFICIENT_BALANCE	402	Клієнт вичерпав і залишок ліміту (квоти), і попередньо поповнений баланс за поточний розрахунковий період.
PROVIDER_CAPACITY_EXCEEDED	429	Глобальна або клієнтська ємність для роботи зі сторонніми джерелами даних заповнена. Жодну перевірку чи резервування коштів не прийнято; повторіть запит через інтервал із Retry-After. У стійкому режимі роботи з джерелами кожна live-перевірка займає до 10 слотів, доки її запити не зафіксовано; типова ємність клієнта — 1000 слотів, тобто 100 live-перевірок, що одночасно чекають на джерела; цього завжди вистачає на один повний пакет зі 100 елементів.
PROVIDER_CAPACITY_REQUEST_TOO_LARGE	422	Цей один запит потребує більше слотів, ніж ємність клієнта чи глобальна ємність містить загалом, тому його не можна прийняти ніколи: повтор не допоможе, а Retry-After не надсилається. Жодну перевірку чи резервування коштів не прийнято; розбийте запит на менші.
RULESET_UNAVAILABLE	503	Під час перевірки жоден опублікований набір правил оцінювання не був досяжним — за такої відповіді перевірку ніколи не тарифікують.
RATE_LIMIT_STORE_UNAVAILABLE	503	Сховище лічильників обмеження частоти запитів недосяжне. Запит відхилено, а не обслужено без обмежень узагалі (fail-closed).
RATE_LIMIT_EXCEEDED	429	Перевищено обмеження частоти запитів: за IP, за викликачем, за невдалою автентифікацією, окреме обмеження на клієнта для rederive чи звітів про адреси або окреме обмеження для документації. Повторіть запит після вікна, названого в Retry-After.
SERVICE_DRAINING	503	Екземпляр завершує роботу й відмовляється від нової роботи; повторіть запит до іншого екземпляра.
UPSTREAM_UNAVAILABLE	503	Залежність, яку цей запит викликає синхронно (DNS-розв'язання URL вебхука, запит до стороннього джерела даних), не відповіла або перевищила час очікування.
REPORT_RENDERING	503	PDF доказового звіту ще генерується й не був готовий за відведений час очікування. Повторіть запит через інтервал із Retry-After; посилання залишається чинним.
REPORT_RENDER_FAILED	503	Не вдалося згенерувати PDF доказового звіту. У повідомленні є короткий ідентифікатор звіту, який слід назвати підтримці; повторне відкриття посилання після короткої паузи ще раз запускає генерацію.
UNSUPPORTED_ASSET	422	Символу активу немає у реєстрі активів, які підтримує рушій скринінгу.
ADDRESS_REQUIRED	422	У перевірці транзакції не вказано address для активу, який не може його визначити (будь-який, крім TRX, ETH, BNB і BASE), або ключ sandbox не вказав його в жодній перевірці транзакції. Передайте адресу вашого клієнта в цій транзакції.
TRANSACTION_UNRESOLVED	422	У перевірці транзакції не вказано address, а транзакцію не вдалося прочитати з її мережі (такої транзакції немає в цій мережі, неможливо розкодувати одержувача депозиту або джерело даних мережі не відповіло вчасно). Нічого не прийнято й не тарифіковано; перевірте хеш і мережу, повторіть запит або передайте адресу.
PAYLOAD_TOO_LARGE	413	Тіло запиту перевищує налаштований ліміт розміру.
IDEMPOTENCY_REQUEST_IN_FLIGHT	409	Запит із цим Idempotency-Key уже обробляється іншим запитом; повторіть невдовзі.
IDEMPOTENCY_LEASE_LOST	409	Оренду ідемпотентності цього запиту перехопив одночасний повторний запит, поки він ще не завершився; повторіть, щоб прочитати записаний, опублікований результат.
CHECK_FAILED	422	Рушій скринінгу відпрацював до кінця, але сама перевірка завершилася помилкою (наприклад, невиправна помилка стороннього джерела даних).
INTERNAL_ERROR	500	Некласифікована серверна помилка. Кожна 5xx, яку ця таксономія не називає окремо (і кожен суто внутрішній код), зводиться до цього коду; сире повідомлення ніколи не залишає журнал сервера.

AMLBot-сумісний ендпоінт

AMLBot-сумісний ендпоінт зберігає конвенцію API, яке відтворює: він завжди відповідає HTTP 200, а збої повідомляє у власному конверті result: false; див. Відповіді у посібнику з міграції. Конверт і коди вище стосуються /v1.