Обмеження частоти запитів і ліміти

Користування API обмежують два окремі механізми: обмеження частоти запитів задає, скільки запитів ви можете надіслати за хвилину, а ліміт (квота) і баланс оплачують перевірки, які ви виконуєте. Вони збоять по-різному, тож і обробляти їх слід по-різному.

Обмеження частоти запитів

Ліміти рахуються за хвилину й окремо для кожної комбінації викликача, HTTP-методу та маршруту: опитування GET /v1/checks/{check_id} не витрачає вашого ліміту для POST /v1/checks. Кожен запит проходить через два пороги, і перший досягнутий відповідає 429.

Поріг	Ліміт за хвилину
За IP-адресою джерела (клієнти IPv6 рахуються за мережею /64)	30
За live-ключем API	60
За ключем API sandbox	10
Невдала автентифікація, за IP-адресою джерела	5
Rederive, на обліковий запис для всіх його ключів	20
Звіти про адреси, на обліковий запис для всіх його ключів	10

Пороги діють на кожен маршрут окремо. Наприклад, один сервер, що надсилає всі live-запити з однієї IP-адреси, досягне порога IP у 30 за хвилину раніше, ніж порога ключа у 60 за хвилину. Щоб перевіряти більше за хвилину, розподіліть трафік між адресами або надсилайте до 100 перевірок в одному запиті POST /v1/checks/batch, який рахується як один запит. Якщо вашому обсягу потрібні вищі ліміти, напишіть на hello@leeri.ai.

Запит, який обмежили, відповідає 429 з RATE_LIMIT_EXCEEDED і такими заголовками:

Заголовок	Значення
`Retry-After`	Секунди до скидання вікна.
`RateLimit-Limit`	Дозволена кількість запитів за вікно для цього викликача, методу та маршруту.
`RateLimit-Remaining`	Скільки запитів залишилося в поточному вікні.
`RateLimit-Reset`	Секунди до скидання вікна.

Зачекайте Retry-After секунд і надішліть той самий запит знову. Забагато невдалих автентифікацій з однієї адреси також дають 429 до кінця хвилини, тож неправильний ключ у циклі повторів блокує цю адресу: зупиняйтеся на 401.

curl
Node.js
Python

curl -s -i -X POST https://api.leeri.ai/v1/checks \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"address","asset":"TRX","address":"'"$ADDRESS"'"}' | grep -i -E '^(HTTP|retry-after|ratelimit)'

async function postWithRetry(url, options) {
  for (let attempt = 1; attempt <= 4; attempt += 1) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const wait = Number(response.headers.get('retry-after') ?? 1);
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error('still rate limited after 4 attempts');
}

import time

import requests


def post_with_retry(url, **kwargs):
    for _ in range(4):
        response = requests.post(url, timeout=30, **kwargs)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "1")))
    raise RuntimeError("still rate limited after 4 attempts")

Як оплачується перевірка

У кожному розрахунковому періоді ваш тариф включає певну кількість перевірок — ліміт (квоту). Перевірка оплачується в такому порядку:

З решти ліміту.
Коли ліміт вичерпано — з попередньо поповненого балансу за ціною однієї перевірки вашого тарифу.
Коли вичерпано обидва, запит відхиляється з 402 INSUFFICIENT_BALANCE, і перевірка не виконується.

Пакет приймається повністю або не приймається взагалі: якщо ліміт і баланс не покривають кожен елемент, відхиляється весь пакет. Тарифи та ціни — на сторінці тарифів.

Що не тарифікується

Повторна перевірка протягом 7 днів. Якщо за ту саму адресу в тому самому ланцюгу з вас стягували плату за останні 7 днів, повторна перевірка безкоштовна — і як перевірка адреси, і як перевірка транзакції. Так можна повторно перевірити клієнта, не платячи двічі.
Перевірки sandbox. Ключ sandbox ніколи не витрачає ліміт чи баланс. Див. Sandbox і live.
Відхилені та невдалі запити. Непідтримуваний актив, помилка валідації, невдала перевірка та RULESET_UNAVAILABLE не тарифікуються ніколи.
Частковий вердикт через недоступне джерело даних. Якщо джерело, від якого залежить вердикт, було недоступне чи застаріле, вердикт повідомляє про це в partial_reasons, а плату повертають: повтор пізніше може його завершити.

Що тарифікується

Завершений вердикт тарифікується. Так само тарифікується частковий вердикт, чия межа — заявлена межа аналізу, а не збій, наприклад обмеження обходу чи глибина «лише прямі контрагенти» в Ethereum, BNB Smart Chain і Base. Такий вердикт — повна послуга для цієї адреси, і повторний запуск нічого не змінює.

Доказовий звіт є частиною перевірки й ніколи не тарифікується окремо. Плату визначають, коли перевірка завершується, тож перевірка в стані pending не є остаточною, доки не завершиться.

Ємність

Live-перевірки, яким потрібне стороннє джерело даних, утримують ємність, доки їхні запити не виконано. Якщо ємність вашого облікового запису заповнена, запит відповідає 429 PROVIDER_CAPACITY_EXCEEDED із Retry-After: 30; нічого не приймається й не тарифікується, тож повторіть після інтервалу. Типова ємність допускає одночасно 100 live-перевірок, що чекають на джерела даних, чого завжди вистачає на один повний пакет зі 100 елементів.

Один запит, якому потрібно більше ємності, ніж обліковий запис має загалом, відповідає 422 PROVIDER_CAPACITY_REQUEST_TOO_LARGE. Він ніколи не вдасться й не має Retry-After: надсилайте менше елементів в одному запиті.

Усі коди — на сторінці Помилки, а нижчий поріг sandbox — на сторінці Sandbox і live.