← Դեպի փաստաթղթեր
LootX

Лимиты и тарифы

Կազմվել է: 2026-11-21 docs.lootx.trade
Лимиты и ошибки

1Лимиты и тарифы

Что ограничивает API-тариф, почему лимиты общие на все ключи аккаунта, как читать заголовки X-RateLimit и RateLimit, живые лимиты /v1/usage и что делать при 429.

Лимиты задаёт API-тариф аккаунта. Он отдельный от подписки на терминал: можно иметь Pro терминала и не иметь API-тарифа, и наоборот. Какой тариф у вас и что в него входит — на странице API-ключи в кабинете.

Что ограничивает тариф

Лимит Как считается
Запросов в минуту ведро с допустимым всплеском: короткая пачка запросов проходит, средний темп — не выше лимита
Запросов в час окно UTC с начала часа, hh:00
Запросов в сутки окно UTC с 00:00
Байт выдачи в сутки по фактически отданному телу ответа и по кадрам WebSocket, сброс в 00:00 UTC
Глубина истории сколько дней назад от «сейчас» можно спрашивать. Это предел, а не обещание глубины: раньше, чем лежат данные, ответ пустой (свечи, например, есть с 23.10.2026 — смотрите coverage), кроме price_step у тепловой карты
WebSocket-соединений одновременно открытых
Рыночных WebSocket-подписок scope: "market", поле тарифа ws_market_subs: на аккаунт — все ключи, соединения и каналы вместе. Ноль — значение шлюза, одна подписка
Ключей действующих ключей на аккаунт

Ноль в тарифе означает «без ограничения» — кроме рыночных подписок: там ноль значит значение шлюза, одну подписку.

Лимиты групп маршрутов

Тариф может дать группе маршрутов свои, более строгие лимиты — например, тепловой карте или секундным свечам — или закрыть группу совсем: тогда ответ 403 route_not_in_plan. Лимит группы действует вместе с общим, а не вместо него: запрос к тепловой карте тратит и запас группы heatmap, и общий запас аккаунта.

Группа Маршруты
instruments /v1/instruments
candles /v1/candles с шагом от минуты
candles_1s /v1/candles с шагом меньше минуты; канал candles в WebSocket
series /v1/series
footprint /v1/footprint, /v1/hyperliquid/footprint
delta /v1/delta
trades /v1/trades
heatmap /v1/heatmap, /v1/book/bands
oi /v1/oi
funding /v1/funding, /v1/funding/events
ls_ratio /v1/ls-ratio, /v1/ls-ratio/latest
mark /v1/mark с шагом 1m и /v1/mark/latest
mark_1s /v1/mark с шагом 1s
margin /v1/margin/*: все шесть маршрутов маржинального кредитования
options /v1/options/*: все десять маршрутов опционов и поток /v1/options/stream — соединение, его кадры и объём; группы ws у потока нет. /v1/options/chain/range весит час диапазона — от 1 до 6 единиц (вес запроса), /v1/options/vol/book-range — границы шага на 64, вверх, от 1 до 34 единиц (вес ряда), /v1/options/levels/range — точки шага на 1440, вверх, от 1 до 7 единиц (вес истории уровней), /v1/options/exposure/latest — 1 единица
densities /v1/densities
densities_history /v1/densities/history
icebergs /v1/icebergs
screener /v1/screener, /v1/screener/metrics
ws подключение к /v1/ws и /v1/ws/*; поток опционов — в группе options

/v1/status не входит ни в одну группу и расходует только общие лимиты; /v1/usage — тоже.

Заголовки

Каждый ответ на запрос с ключом — и успешный, и с ошибкой — несёт состояние лимитов. Две записи одного и того же: короткая X-RateLimit-* — по самому тесному окну, где осталось меньше всего, и RateLimit-Policy с RateLimit по черновику IETF (draft-ietf-httpapi-ratelimit-headers) — по всем окнам тарифа сразу.

HTTP
HTTP/1.1 200 OK
X-Request-Id: 9f2c4a1be07d4e55a1c3b2d4e5f60718
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1793793601
X-RateLimit-Scope: account
X-RateLimit-Window: minute
RateLimit-Policy: "minute";q=600;w=60, "day";q=50000;w=86400, "bytes_day";q=10737418240;w=86400;qu="content-bytes"
RateLimit: "minute";r=99;t=1, "day";r=45000;t=43200, "bytes_day";r=10733418240;t=43200
Заголовок Смысл
X-RateLimit-Limit потолок самого тесного окна; у минуты — запросов в минуту, у bytes_day — байт в сутки
X-RateLimit-Remaining сколько в нём осталось
X-RateLimit-Reset когда это окно сбросится — момент, Unix-секунды UTC. У минуты — когда ведро снова полное
X-RateLimit-Scope account — общий лимит аккаунта, route:<группа> — лимит группы
X-RateLimit-Window minute, hour, day или bytes_day
RateLimit-Policy все окна тарифа для этого запроса: q — потолок, w — длина окна в секундах, у байтов — qu="content-bytes". Окна группы называются "route:<группа>:<окно>"
RateLimit остаток r и секунд до сброса t по каждому окну с потолком
Retry-After только у 429 и 503: через сколько секунд повторить

Окно без потолка (0 в тарифе) в RateLimit-Policy и RateLimit не попадает. Все эти заголовки, как и X-Request-Id, X-Next-Cursor, Link и X-Cache, открыты браузеру (Access-Control-Expose-Headers): fetch со страницы их читает.

Предохранитель по адресу

Перед шлюзом стоит край сети, и у него свой предохранитель — по IP-адресу, до проверки ключа: около 50 запросов в секунду с одного адреса, короткий залп — до 100. Сверх него — 429 rate_limited со scope: "ip", window: "second" и retry_after: 1. Это защита от залпов, а не тариф: обычному клиенту, который держится в лимите тарифа, до него не дойти. Несколько сервисов за одним NAT делят этот предохранитель между собой.

Ответы края сети — того же вида, что ошибки шлюза: JSON с code. Кроме 429 это 413 payload_too_large (тело запроса больше 64 КБ) и 503 unavailable / 504 upstream_timeout с Retry-After: 5, если шлюз недоступен или не ответил.

Когда лимит исчерпан

Код HTTP Что случилось Когда пройдёт
rate_limited 429 темп в минуту — аккаунта или группы через Retry-After секунд
hourly_limit 429 запросы за час в начале следующего часа UTC
daily_limit 429 запросы за сутки в 00:00 UTC
daily_quota_exceeded 429 суточный объём выдачи в 00:00 UTC
ws_limit 429 открыто слишком много WebSocket закройте лишнее соединение
market_subs_limit кадр потока рыночных подписок столько, сколько разрешает тариф снимите лишнюю: unsubscribe со scope: "market"
rate_limited кадр потока сверх 10 команд в секунду и запаса 20 на соединение или рыночная подписка канала открывается чаще раза в секунду. Считается открытие: снятие с повторной подпиской паузу не обходит через retry_after секунд; прежняя подписка, если она есть, остаётся
history_out_of_plan 403 запрошено глубже разрешённой истории сдвиньте from не раньше earliest_allowed_ms; у /v1/margin/assets, /compare и /events глубину меряет окно — возьмите window короче; у /v1/options/chain — минута at: at не раньше earliest_allowed_ms; у /v1/options/chain/range — from, округлённый вверх до минуты; у /v1/options/vol/book-range и /v1/options/levels/range отказ приходит уже после списания полного веса
route_not_in_plan 403 группа маршрута не входит в тариф смените тариф

В теле 429 — детали лимита: limit, remaining, window, scope, retry_after и reset_at_ms. У 403 history_out_of_plan — history_days, earliest_allowed_ms и scope, у 403 route_not_in_plan — только scope (тело ошибки).

Что отказ делает со счётчиками:

  • 429 по окнам часа и суток и по объёму, как правило, не двигает ни одного счётчика: запрос не засчитан, повторять после Retry-After безопасно. Исключение — гонка параллельных запросов: окна часа и суток сверяются до вёдер минуты, а засчитываются после них, и если между сверкой и зачётом окно заполнил соседний запрос, отказ придёт уже после того, как этот запрос потратил жетон минутного ведра аккаунта (и группы, если у неё свой темп). Сами окна часа и суток он при этом не засчитывает. Объём суток так не гоняется: он сверяется только до вёдер.
  • 429 rate_limited по ведру группы не двигает ничего. По ведру аккаунта — тоже, кроме одного: жетон ведра группы этого запроса уже списан. Потеря — не больше ёмкости ведра группы и только когда вы и так упёрлись в общий лимит.
  • 403 history_out_of_plan — уже засчитанный запрос: он расходует окна минуты, часа и суток, как обычный.
  • 403 route_not_in_plan счётчиков не двигает.

И ещё:

  • Объём учитывается после ответа: запрос, начатый до исчерпания, отдаётся целиком, следующий получит 429.
  • Ответ из кэша шлюза (X-Cache: HIT) считается в лимитах и объёме как обычный.
  • Объём считается по телу до сжатия: со сжатием и без запрос стоит одинаково (сжатие).
  • 503 upstream_busy — не ваш лимит, а очередь шлюза к источнику: она защищает источники от всплесков. Повторите через Retry-After (обычно 1 с).
Python
import time, requests

WAIT_FOR_RESET = ("daily_limit", "daily_quota_exceeded", "hourly_limit", "ws_limit")

def get(url, **kw):
    for attempt in range(4):
        r = requests.get(url, **kw)
        if r.status_code in (429, 503):
            err = r.json()["error"]
            if err["code"] in WAIT_FOR_RESET:
                raise RuntimeError(f"лимит {err['code']}: окно сбросится в {err.get('reset_at_ms')}")
            time.sleep(min(int(err.get("retry_after") or r.headers.get("Retry-After", 1)), 30))
            continue
        return r
    return r

Такой же цикл есть в SDK, но пакеты SDK ещё не опубликованы: код лежит в репозитории шлюза.

WebSocket в суточном объёме

Байты кадров, которые сервер шлёт клиенту, идут в суточный объём вместе с REST: данные любых каналов /v1/ws, ответы на команды, кадры сырых потоков /v1/ws/* и hello с кадрами OPC1 потока /v1/options/stream. Считается длина кадра без служебных заголовков WebSocket. WS-ping и кадр error, с которым шлюз закрывает соединение, не считаются.

Учёт тот же, что у REST: общий объём аккаунта, группа соединения ws и группа данных канала (densities, screener, trades, oi, candles_1s); у потока опционов — общий объём и группа options, те же письма на 80 и 100 %. Лимит объёма группы действует и на кадры: лимит ws тратят все эти кадры соединения, лимит группы канала — только кадры этого канала. В разбивке расхода по группам ответы на команды, subscribed рыночной подписки тоже, стоят в ws, данные — в группе канала.

Кадры копятся и списываются раз в такт соединения (5 с) и при закрытии, поэтому перерасход — не больше одного такта потока.

Когда объём кончился:

  • /v1/ws — кадр error с кодом daily_quota_exceeded (limit, remaining: 0, window: "bytes_day", scope — account или route:<группа>) и закрытие 1008 с тем же кодом в причине;
  • сырой поток /v1/ws/* и поток опционов — закрытие с кодом в причине;
  • новое соединение — 429 daily_quota_exceeded, как у REST;
  • новая рыночная подписка на открытом соединении — отказ кадром error с тем же кодом.

Если счётчики объёма временно недоступны, поток не рвётся, а прибавка за это время теряется.

Живые лимиты: GET /v1/usage

GET/v1/usage

Тариф ключа, его лимиты, расход за сутки UTC и состояние каждого окна прямо сейчас. Сам запрос — обычный: он расходует общие окна аккаунта (минуту, час, сутки и байты), но не лимиты групп — ни в одну группу он не входит.

Shell
curl -s "https://market-api.lootx.trade/v1/usage" -H "Authorization: Bearer $LOOTX_API_KEY"
JSON
{
  "plan": { "id": "6f1c…", "slug": "pro", "name": "Pro" },
  "tier": "pro",
  "limits": { "rpm": 600, "burst": 100, "rph": 0, "rpd": 50000, "daily_bytes": 10737418240, "history_days": 365, "ws_conns": 5 },
  "routes": { "heatmap": { "rpd": 5000, "rpm": null, "rph": null, "daily_bytes": null, "history_days": null, "enabled": true } },
  "today": { "day": "2026-11-04", "requests": 5000, "bytes": 4000000 },
  "now": {
    "at_ms": 1793793600000,
    "windows": [
      { "scope": "account", "window": "minute", "limit": 600, "burst": 100, "used": 37, "remaining": 63, "reset_at_ms": 1793793603700 },
      { "scope": "account", "window": "hour", "limit": null, "used": 1234, "remaining": null, "reset_at_ms": 1793797200000 },
      { "scope": "account", "window": "day", "limit": 50000, "used": 5000, "remaining": 45000, "reset_at_ms": 1793836800000 },
      { "scope": "account", "window": "bytes_day", "limit": 10737418240, "used": 4000000, "remaining": 10733418240, "reset_at_ms": 1793836800000 },
      { "scope": "route:heatmap", "window": "day", "limit": 5000, "used": 10, "remaining": 4990, "reset_at_ms": 1793836800000 }
    ],
    "throttled_today": 3,
    "last_limited": { "at_ms": 1793793500000, "code": "rate_limited", "scope": "account", "window": "minute" }
  }
}
Поле Что
plan, tier тариф ключа
limits общие лимиты аккаунта; 0 — без ограничения. ws_market_subs приходит, только если тариф задал его не нулём; нет поля — значение шлюза, одна подписка
routes группы тарифа так, как их применяет шлюз: enabled — открыта ли группа на деле (false — закрыта: запросы к ней получают 403 route_not_in_plan); в лимите null — как в общем, 0 — без ограничения в группе
today за сутки UTC: засчитанные запросы (429 и 403 route_not_in_plan не входят, 403 history_out_of_plan входит) и отданные байты до сжатия
now.windows окна сейчас: общие — всегда, окна группы — только у групп со своим лимитом
now.throttled_today сколько раз за сутки UTC запрос отбит по лимиту (429 и лимитные 403)
now.last_limited последний такой отказ за сутки или null

Окно в now.windows:

Поле Минута Час, сутки, байты
limit установившаяся скорость, запросов в минуту потолок окна; у bytes_day — байт
burst ёмкость ведра: сколько запросов можно подряд нет
remaining целые жетоны в ведре сейчас, с пополнением сколько осталось до потолка
used burst − remaining сколько уже засчитано
reset_at_ms когда ведро снова полное когда окно сбросится

limit: null и remaining: null — у окна нет потолка. Заполнение минуты считайте как used / burst, а не used / limit: минута — ведро, а не счётчик.

Счётчики лимитов временно недоступны — 503 usage_unavailable с Retry-After, а не ответ с пустыми окнами или нулями: повторите позже. На ваши запросы к остальным маршрутам это не влияет.

Уведомления о расходе

Когда расход за сутки или за час доходит до 80 % и до 100 % лимита — общего или лимита группы, — на почту аккаунта приходит письмо. Следим за суточным объёмом, запросами в сутки и запросами в час. Одно письмо на порог: на суточные лимиты — раз в сутки, на часовой — раз в час.

Где смотреть расход

Кабинет → API-ключи → Расход:

  • запросы и объём по дням за 7 или 30 суток UTC, с долей ошибок и отказов 429. Подключение WebSocket считается запросом, поток — нет: его кадры дают только объём. До 06.11.2026 17:17 UTC запросами считались и такты соединения, эти итоги не пересчитаны;
  • разбивка по ключам или по группам маршрутов;
  • расход за сегодня (UTC) против лимитов тарифа: от 80 % — предупреждение, на 100 % — лимит исчерпан.

Живой остаток в своём коде — из заголовков X-RateLimit-* и RateLimit любого ответа или целиком из /v1/usage.

https://docs.lootx.trade/hy/market-api/limits