LootX

Ошибки

Updated November 21, 2026 This page as PDF

Тело ошибки с деталями, все коды REST и WebSocket — что значит каждый и что с ним делать.

This page is not translated into your language yet — showing the original.

Тело ошибки

Любая ошибка шлюза — HTTP-код и JSON, в каком бы формате вы ни просили ответ: и отказ маршрута, и неизвестный путь, и неподдержанный Accept, и внутренний сбой.

JSON
{
  "error": {
    "code": "rate_limited",
    "message": "лимит 600 запросов в минуту исчерпан",
    "request_id": "9f2c4a1be07d4e55a1c3b2d4e5f60718",
    "docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#rate_limited",
    "limit": 600,
    "remaining": 0,
    "window": "minute",
    "scope": "account",
    "retry_after": 1,
    "reset_at_ms": 1793750461000
  }
}
Поле Что
code машинный код, snake_case, стабильный. Разбирайте его
message объяснение для человека; может меняться, не разбирайте его
request_id тот же номер, что в заголовке X-Request-Id. Пришлите его в поддержку
docs_url этот код на этой странице: https://docs.lootx.trade/ru/market-api/error-codes#<код>

Детали

Рядом с code лежат поля, которые помогают исправить запрос. Каждое есть, только когда оно к месту:

Когда Поля Что в них
400 — параметр не разобрался param, expected какой параметр и что в нём ожидалось: "param": "from", "expected": "целое: Unix-миллисекунды UTC"
406 not_acceptable param, expected "param": "Accept" и список типов, которые отдаёт этот маршрут
429 limit, remaining, window, scope, retry_after, reset_at_ms потолок окна и остаток; окно — minute, hour, day, bytes_day (у края сети — second); чьё — account, route:<группа> или ip; через сколько секунд повторить; когда окно сбросится, Unix-мс UTC
403 history_out_of_plan history_days, earliest_allowed_ms, scope, param, expected глубина истории тарифа в сутках (с учётом группы); самый ранний допустимый from, Unix-мс UTC; чей предел — account или route:<группа>; "param": "from", а у маршрутов маржи с окном — "param": "window", у /v1/options/chain — "param": "at"
403 route_not_in_plan scope закрытая группа — route:<группа>
405 method_not_allowed allow разрешённые методы — как в заголовке Allow

У bytes_day limit и remaining — в байтах. Как устроены окна — Лимиты и тарифы.

Заголовки ошибки

Заголовок Когда
X-Request-Id у каждого ответа
Retry-After у каждого 429 и 503 — через сколько секунд повторить; у 503 без своего срока — 5
WWW-Authenticate у 401: Bearer realm="lootx", а с негодным ключом — Bearer realm="lootx", error="invalid_token"
Allow у 405 и у OPTIONS: GET, HEAD, OPTIONS
X-RateLimit-*, RateLimit-Policy, RateLimit у ответов с ключом, и с ошибкой тоже — подробно

Ключ и доступ

Код HTTP Что значит Что делать
missing_key 401 ключа нет передайте Authorization: Bearer <ключ> или X-API-Key
invalid_key 401 такого ключа нет проверьте, что ключ скопирован целиком: lx_live_ и 43 знака. Повтор с тем же ключом не поможет
invalid_token 401 токен входа не прошёл проверку для API используйте ключ, а не токен терминала
token_expired 401 срок токена входа истёк то же
key_in_query 400 ключ передан в адресе уберите ключ из адреса — только заголовок. Ключ, засветившийся в адресе, лучше отозвать
revoked_key 403 ключ отозван выпустите новый в кабинете
plan_inactive 403 у аккаунта нет действующего API-тарифа продлите или выберите тариф
insufficient_scope 403 у ключа нет нужной области доступа. У /v1/options/* нужна область derivatives: токен терминала без неё (бесплатный) получает этот отказ выпустите ключ с нужными областями; к опционам — с API-ключом
route_not_in_plan 403 группа маршрута не входит в тариф смените тариф; что в него входит — в кабинете
history_out_of_plan 403 история глубже, чем разрешает тариф (общий лимит или лимит группы). У /v1/margin/assets, /compare и /events глубину меряет окно window — param: "window"; у /v1/options/chain — начало минуты, закрытой в at, — param: "at" сдвиньте from не раньше earliest_allowed_ms из тела ошибки; у маржи с окном — возьмите window короче; у опционов — at не раньше earliest_allowed_ms
forbidden 403 доступ запрещён по иной причине проверьте ключ и тариф; не проходит — напишите в поддержку с request_id
auth_unavailable 503 проверка ключа временно недоступна повторите через Retry-After

Лимиты

Код HTTP Что значит Что делать
rate_limited 429 превышен лимит запросов в минуту — аккаунта или группы маршрутов (scope); со scope: "ip" — предохранитель края сети по адресу подождите Retry-After секунд; держите темп ниже RateLimit-Policy
hourly_limit 429 исчерпан лимит запросов в час сброс в начале следующего часа UTC — reset_at_ms
daily_limit 429 исчерпан лимит запросов в сутки сброс в 00:00 UTC — reset_at_ms
daily_quota_exceeded 429 исчерпан суточный объём выдачи — аккаунта или группы; кадры WebSocket считаются в него же сброс в 00:00 UTC; protobuf и бинарь тепловой карты короче JSON
ws_limit 429 слишком много одновременных WebSocket закройте лишнее соединение

Подробно про лимиты, заголовки и живой остаток — Лимиты и тарифы.

Параметры запроса

Код HTTP Что значит Что делать
bad_request 400 параметры не разобрались исправьте параметр из param по expected
bad_instrument 400 инструмент не в виде venue:market:SYMBOL как называть инструменты
unsupported_instrument 400 инструмента нет у источника: param: "instrument" — биржа, рынок или котировка, param: "symbol" — символ, только на /v1/candles и /v1/series и не всегда. На остальных маршрутах символ не сверяется: пустой 200 не значит, что инструмент есть. Условия и пределы проверьте имя и колонку sources в /v1/instruments
bad_cursor 400 курсор не разобрался: он повреждён. С параметрами запроса он не сверяется передавайте next_cursor (или ссылку из Link) из прошлого ответа без изменений, с теми же остальными параметрами
bad_format 400 неизвестный format, или CSV для ответа из нескольких таблиц, или формат не этого маршрута: CSV у ответов без таблицы (/v1/status, /v1/margin/coverage, опционы) — и format=csv, и Accept: text/csv, opc1 вне /v1/options/chain, /chain/latest и /chain/range — в том числе у /v1/options/vol/book-range, /exposure/latest и /levels/range message называет форматы маршрута: format=json, protobuf или csv, у ответов без таблицы — format=json или protobuf; для футпринта — table=levels или windows
not_acceptable 406 в Accept нет ни одного известного шлюзу типа — ни JSON, ни protobuf, ни text/csv, ни маски вроде */*. Accept: text/csv у ответа без таблицы — не 406, а 400 bad_format Accept: application/json, application/x-protobuf или text/csv — или ?format=. У ответов без таблицы (/v1/status, /v1/margin/coverage, опционы) в expected типы без text/csv; кадры OPC1 цепочек опционов — только ?format=opc1, по Accept их не попросить
method_not_allowed 405 метод не GET, HEAD или OPTIONS метод из Allow (GET, HEAD, OPTIONS)
request_timeout 408 запрос не дошёл до шлюза вовремя повторите запрос
payload_too_large 413 тело запроса больше 64 КБ запросам API тело не нужно — отправляйте GET без тела
too_large 413 ответ слишком велик сузьте окно, укрупните шаг или возьмите бинарный формат
not_found 404 нет такого маршрута. У /v1/ls-ratio/latest и /v1/mark/latest — по инструменту нет ни одной строки: у long/short за 35 суток, у mark за 7 суток. У /v1/options/chain и /chain/latest — нет минуты у базы или у присланной chain либо она не восстанавливается (gap в message); у /chain/range — нет цепочки, инструмента или ни одной минуты диапазона; у /vol/book-range, /exposure/latest и /levels/range — нет книги у базы; у потока опционов — нет присланной цепочки или у базы нет ни одной, отказ до апгрейда список маршрутов — /v1/openapi.json; замолчавший ряд читайте /v1/ls-ratio или /v1/mark с окном
not_available 404 маршрут есть, но таких данных шлюз не отдаёт: их ещё не собирают или они не включены у источника. Это не ошибка запроса и не сбой источника повтор не поможет; какие маршруты отвечают так — в описании ответов /v1/openapi.json

Неизвестный инструмент

unsupported_instrument приходит в двух случаях, в REST их различает поле param. В потоке различителя нет: подписка символ не сверяет.

  • param: "instrument" — биржа, рынок или котировка. Отказ приходит сразу, до запроса к источнику: binance:future:BTCUSDT, спот у /v1/oi, биржа, которой нет у маршрута. /v1/oi, /v1/funding, /v1/funding/events, /v1/ls-ratio и /v1/ls-ratio/latest у okx, bingx, mexc и kucoin, а /v1/mark и /v1/mark/latest у okx и mexc собирают имя для источника из базы и котировки, поэтому так же отказывают символу, котировку которого не разобрать: okx:perp:BTC-USDT-SWAP, kucoin:perp:XBTUSDTM. Свои правила у /v1/screener?instruments=: биржу он не сверяет, а котировку сверяет.
  • param: "symbol" — символ. Только /v1/candles и /v1/series: биржа и рынок есть, а символ не найден, например binance:perp:BTCUSDTT. В message — что не найдено и ссылка на /v1/instruments?venue=…&market=….

На остальных маршрутах пустой ответ не значит, что инструмент существует. /v1/trades, /v1/footprint, /v1/delta, /v1/heatmap, /v1/oi, /v1/funding, /v1/funding/events, /v1/ls-ratio, /v1/mark, /v1/densities, /v1/densities/history, /v1/icebergs и /v1/screener?instruments= на символ, по которому нет данных, отвечают 200 с пустым ответом, на опечатку тоже, если имя прошло проверки выше. Исключение — /v1/heatmap с price_step: без данных книги в минуте перед to шаг не во что перевести, ответ 400 bad_request, запрашивайте без него. Условие и оговорка — в пределах тепловой карты. Живые списки источников не знают снятые символы с историей, поэтому отказ по ним был бы ложным.

Отказ с param: "symbol" не гарантирован. Он приходит, только когда сошлось всё:

  1. Строк нет, в запросе нет cursor, а в ответе не было бы next_cursor. Есть строки — они отдаются, даже если инструмент снят с торгов и ни в одном списке его больше нет.
  2. Источник подтвердил, что по символу нет ни одного бара за всю историю, а не только в окне запроса. Не смог подтвердить или запись баров у него выключена — отказа нет.
  3. Рынок вообще есть у источника свечей. Рынков HIP-3 там нет, см. ниже.
  4. Символа нет ни в одном списке источников, и шлюз не видел его в них с момента своего запуска. Имена сравниваются по базе без учёта регистра: BTC, BTCUSDC и btcusdt одной биржи и рынка — один инструмент. Поэтому BTCEUR на бирже с BTCUSDT, но без такой пары, отказа не получит.
  5. Все источники списков исправны: каждый недавно отдал непустой список, хотя бы в одном есть эта биржа и рынок, и с первого списка источника прошло достаточно времени. Источник только поднялся или вернулся после долгого сбоя — отказ включится не сразу.

Иначе ответ — 200 с пустым списком. Поэтому при сбое одного источника или вскоре после перезапуска шлюза опечатка на /v1/candles и /v1/series тоже может получить 200. Глубина истории проверяется раньше: 403 history_out_of_plan приходит до запроса к источнику, и отказ по символу его не заменяет.

400 бывает и у настоящего инструмента. Когда условия выше сошлись, это:

  • Новый листинг. Пока символа нет ни в одном списке, а первая сделка не дошла до баров, /v1/candles и /v1/series отвечают 400. Повторите позже.
  • Символа нет в барах, а в других данных он есть. Снятый с торгов, когда свечей по этой бирже ещё не писали, или с истёкшими барами. 400 здесь говорит о свечах и рядах: у /v1/footprint, /v1/trades и других маршрутов данные по нему могут быть.
  • Имя не в том виде, что в реестре. PF_XBTUSD, BTC-USDT-SWAP, XBTUSDTM, BTC_USDT к имени источника не приводятся. Имя берите из /v1/instruments: там это, например, kraken:perp:BTCUSD, okx:perp:BTCUSDT, kucoin:perp:BTCUSDT.

Акции Hyperliquid (рынки HIP-3) пишутся как в /v1/instruments: hyperliquid:perp:AAPLUSDC.XYZ, короткое hyperliquid:perp:AAPL.XYZ — то же самое. Данные по ним есть у /v1/footprint, /v1/delta, /v1/trades и /v1/heatmap (только деки xyz и io), у /v1/densities и /v1/screener. У /v1/candles, /v1/series, /v1/oi, /v1/funding и /v1/funding/events этих рынков нет: ответ — пустой 200, отказа нет. Имя Hyperliquid xyz:AAPL не подходит: двоеточие в символе — 400 bad_instrument.

Источники данных и шлюз

Код HTTP Что значит Что делать
upstream_rejected 400 источник отверг параметры запроса. У /v1/margin/* текст источника начинается с имени параметра — оно же в param; у /v1/options/* param — по коду источника (bad_base → base, bad_range → from, range_too_long → to, bad_instrument → instrument, bad_resume → resume, …), код — в конце message проверьте окно и шаг; message подскажет
upstream_error 502 источник ответил ошибкой. У /v1/margin/* и /v1/options/* так же приходит и 404 источника без кода минуты: маршрутов у него нет, это не not_found повторите позже; если повторяется — напишите в поддержку с request_id
upstream_unavailable 502 источник недоступен. У /v1/margin/* — ещё и 503 с Retry-After: 2: источник прогревается или перегружен (подробно); у /v1/options/* — 503 с Retry-After источника, обычно 1 с, не дольше 60 с: источник загружает цепочки после запуска, у /v1/options/vol/book-range уже собирает предельное число рядов со склада, у /v1/options/levels/range — читает предельное число рядов уровней, у потока опционов держит предельное число соединений; поток выключен на узле — 503 с Retry-After: 30, это выкладка, а не окончательный отказ (подробно) повторите позже; состояние — /v1/status
upstream_timeout 504 источник или шлюз не ответил вовремя сузьте окно или повторите через Retry-After
upstream_busy 503 очередь шлюза к источнику полна повторите через Retry-After, обычно 1 с
upstream_not_configured 503 источник ещё не подключён к шлюзу маршрут в бете — следите за обновлениями
usage_unavailable 503 /v1/usage: счётчики лимитов временно недоступны повторите через Retry-After
unavailable 503 сервис временно недоступен (в том числе край сети не достучался до шлюза) повторите через Retry-After, у края сети — 5 с
internal 500 внутренняя ошибка шлюза напишите в поддержку с request_id

Поток (WS)

Ошибки потока приходят кадром error того же вида, что тело ошибки REST: code, message, docs_url, id команды, если он был, и детали лимита, когда они к месту. Соединение при этом живёт, кроме отмеченных «закрытие».

JSON
{"type": "error", "id": 7, "code": "rate_limited",
 "message": "не больше 10 сообщений в секунду на соединение (запас 20); сообщение пропущено",
 "docs_url": "https://docs.lootx.trade/ru/market-api/error-codes#rate_limited",
 "limit": 10, "remaining": 0, "window": "second", "scope": "connection", "retry_after": 1}
Код Что значит
bad_request кадр не JSON или не текстовый, нет channel, неизвестный op, в subscribe без scope нет непустого массива instruments
unknown_channel такого канала нет
channel_unavailable канал пока не работает или, с instrument, выбрал потолок соединений с источником — повторите позже. Со scope: "market" и channel — потолок рыночных соединений шлюза (retry_after — через сколько секунд повторить); без retry_after — рыночную подписку остановил сбой шлюза, подпишитесь заново
too_many_instruments аккаунт уже держит свою долю ёмкости канала — отпишитесь от лишнего
bad_instrument имя не в виде venue:market:SYMBOL. Кадр несёт instrument, если имя пришло строкой; остальные имена команды обрабатываются дальше
unsupported_instrument у источника канала нет такого рынка или биржи, а на oi и screener ещё и не разобралась котировка символа. Кадр несёт instrument, поля param в нём нет: случаи он не различает. Символ подписка не сверяет (подробно)
bad_params неверные params или scope, что не так — в тексте ошибки: params у подписки по инструментам, кроме null и пустого объекта, scope не market и не null, subscribe со scope: "market" у канала без рыночной подписки или вместе с непустым массивом instruments, параметр рыночной подписки вне списка или с неверным значением
market_subs_limit аккаунт уже держит столько рыночных подписок, сколько разрешает тариф (ws_market_subs, все ключи и соединения вместе). limit, remaining: 0, scope: "account", window: "concurrent". Снимите лишнюю — unsubscribe со scope: "market" — или смените тариф
route_not_in_plan группа канала не в тарифе; без instrument и channel — тариф лишился группы ws: закрытие 1008
too_many_subscriptions больше 200 подписок на соединение; команда отвергнута целиком. limit и remaining — сколько можно и сколько осталось
rate_limited сверх 10 команд в секунду и запаса 20; команда пропущена. scope: "connection", window: "second". То же у рыночной подписки канала, открытой на соединении чаще раза в секунду, заменой или снятием с повторной подпиской: limit: 1, remaining: 0, retry_after — секунд до следующего открытия, прежняя подписка, если она есть, остаётся
ws_limit слот соединения потерян: у аккаунта открыто больше соединений, чем ws_conns тарифа. window: "concurrent", retry_after: 5; закрытие 1013
slow_consumer клиент не успевает читать: очередь переполнена, кадр рыночной подписки не встал в очередь за 10 секунд, очередь забита целиком дольше 10 секунд и ответу на команду некуда встать или накопленные изменения вышли за потолок шлюза. Закрытие 1008
daily_quota_exceeded кончился суточный объём: limit, remaining: 0, window: "bytes_day", scope — account или route:<группа>. Открытое соединение закрывается 1008, новая рыночная подписка получает отказ тем же кодом
revoked_key, plan_inactive, invalid_key, insufficient_scope доступ кончился посреди соединения: закрытие 1008 с кодом в причине

Поток опционов /v1/options/stream кадров error не шлёт: отказы приходят HTTP-ответом до апгрейда, закрытия — кодом и причиной (4008, 1011, 1001, 1013, 1008), подробно — живой поток.

Подробно — Потоки WebSocket.