Лимиты и тарифы
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) — по всем окнам тарифа сразу.
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 с).
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
/v1/usageТариф ключа, его лимиты, расход за сутки UTC и состояние каждого окна прямо сейчас. Сам запрос — обычный: он расходует общие окна аккаунта (минуту, час, сутки и байты), но не лимиты групп — ни в одну группу он не входит.
curl -s "https://market-api.lootx.trade/v1/usage" -H "Authorization: Bearer $LOOTX_API_KEY"{
"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 % лимита — общего или лимита группы, — на почту аккаунта приходит письмо. Следим за суточным объёмом, запросами в сутки и запросами в час. Одно письмо на порог: на суточные лимиты — раз в сутки, на часовой — раз в час.
Где смотреть расход
- запросы и объём по дням за 7 или 30 суток UTC, с долей ошибок и отказов
429. Подключение WebSocket считается запросом, поток — нет: его кадры дают только объём. До 06.11.2026 17:17 UTC запросами считались и такты соединения, эти итоги не пересчитаны; - разбивка по ключам или по группам маршрутов;
- расход за сегодня (UTC) против лимитов тарифа: от 80 % — предупреждение, на 100 % — лимит исчерпан.
Живой остаток в своём коде — из заголовков X-RateLimit-* и RateLimit любого ответа или целиком из /v1/usage.
https://docs.lootx.trade/uk/market-api/limits