Какие ошибки стоит повторять?

429 — с задержкой, 502 — один раз сразу. 403 не повторяйте: ни один из вариантов не станет верным со второй попытки. -400 из обхода транзакций тоже не повторяйте — это граница, а не сбой. 651 означает, что нода отстаёт или блок вне её хранилища: для свежего блока подождите и повторите, для старого используйте архив.

Почему я получаю 403 на getTransactions, но не на getAccountState?

getAccountState читает текущее состояние, которое у лёгкой ноды есть всегда. Обход транзакций идёт назад во времени, и когда он выходит за окно лёгкой ноды примерно в два дня, шлюз направляет его на архивную ноду — а тариф без архива ею пользоваться не может. Текст 403 называет причину: archive history is not included in this plan.

В чём разница между 651 и -503?

651 — это ErrorCode::notready в софте ноды: данные в принципе существуют, но у этой ноды они не готовы — блок ещё не применён или lt вне её базы. -503 timeout — собственный дедлайн ноды на запрос: данные были, но собрать ответ вовремя не удалось.

Почему моя библиотека показывает не ту ошибку, что в таблице?

Библиотеки по-разному оборачивают liteServer.error. tonutils-go хранит код в ton.LSError, pytoniq бросает LiteServerError с кодом и сообщением, а ton-lite-client — Error только с текстом. Если кода нет, сопоставляйте по тексту.

Бесплатные инструменты

Коды ошибок TON liteserver

Каждая liteServer.error, которую может вернуть шлюз TONNode или нода TON, с описанием того, что произошло и что делать. Строки шлюза взяты из документации LiteServers; строки ноды и клиента ссылаются на место в ton-blockchain/ton, где они возникают.

Поиск

Показано 18 из 18 кодов

Код	Сообщение	Что произошло	Что делать
403	`archive history is not included in this plan` Шлюз TONNode	Запросу понадобился блок, которого лёгкая нода уже не хранит, а в тарифе нет архива. Лёгкая нода держит около двух дней истории при текущей скорости блоков; всё более старое шлюз направляет на архивную ноду и отказывает, если тариф её не включает.	Добавьте архив в тариф или запросите более свежий блок. Повторять бессмысленно: тот же запрос будет отклонён снова. Источник: LiteServers docs, Chapter 4
403	`method not supported` Шлюз TONNode	Тип запроса отсутствует в таблице методов шлюза, либо отправлен пакет длиннее, чем префикс waitMasterchainSeqno плюс один запрос.	Используйте документированный метод без префикса или с одним префиксом. Добавление архива в тариф этого не изменит. Источник: LiteServers docs, Chapter 5
429	`too many requests` Шлюз TONNode	Лимит скорости тарифа — leaky bucket на каждый API-ключ в единицах стоимости: обычное чтение стоит 5, полная страница getTransactions — до 16, целый блок — 50.	Сделайте паузу и повторите. Если это постоянно, ограничьте темп клиента скоростью пополнения тарифа или повысьте тариф. Источник: LiteServers docs, Chapter 7
429	`too many concurrent requests for this key` Шлюз TONNode	С этого ключа одновременно было открыто больше запросов, чем позволяет тариф: половина его RPS, но не меньше 8 и не больше 128. Это потолок на запросы в полёте, а не на скорость.	Ограничьте параллелизм: неограниченный Promise.all или веер горутин упирается в этот лимит задолго до лимита скорости. Источник: LiteServers docs, Chapter 7
429	`gateway is saturated, retry shortly` Шлюз TONNode	Достигнут общий потолок в 256 запросов в полёте по всем клиентам. Проблема у бэкенда, а не у вашего тарифа.	Повторите с экспоненциальной задержкой. Источник: LiteServers docs, Chapter 7
502	`backend node timeout` Шлюз TONNode	Нода не ответила в окно шлюза: 7 с для лёгкой ноды, 20 с для архива.	Повторите один раз сразу. Установите собственный таймаут клиента выше этих значений, иначе реальная ошибка превратится в локальный таймаут и диагноз потеряется. Источник: LiteServers docs, Chapter 5
400	`canceled` Шлюз TONNode	Ваш контекст или соединение исчезли посреди запроса — обычно сработал ваш собственный таймаут.	Проблема на стороне клиента. Поднимите таймаут клиента выше окон шлюза 7 с / 20 с. Источник: LiteServers docs, Chapter 5
400	`non zero mode is not supported` Шлюз TONNode	getMasterchainInfoExt вызван с mode, отличным от 0.	Отправьте mode: 0. Источник: LiteServers docs, Chapter 5
-400	`unknown request type` Шлюз TONNode	Метод проходит проверку тарифа, но обработчик запросов шлюза его не реализует.	Повторять нечего. Используйте метод, отмеченный как поддерживаемый в справочнике методов. Источник: LiteServers docs, Chapter 5
500	`failed to …` Шлюз TONNode	Шлюз не смог собрать ответ.	Повторите. Если повторяется, проблема на нашей стороне — напишите в поддержку с id ключа и временем. Источник: LiteServers docs, Chapter 5
-400	`cannot locate transaction in block with specified logical time` Нода TON	Обход getTransactions дошёл до транзакции, которую нода не находит в ожидаемом блоке: чаще всего обход вышел за окно хранения лёгкой ноды.	На архивном тарифе шлюз автоматически повторяет запрос к архиву. Без архива это граница истории — не сбой, повторять не нужно. Источник: validator/impl/liteserver.cpp, LiteQuery::continue_getTransactions
-400	`… (other node text)` Нода TON	Сама нода не выполнила запрос и вернула свой текст; -400 — код по умолчанию для ошибки LiteQuery в софте ноды. Типичные тексты: invalid block id requested, shard not found, cannot unpack block header.	Прочитайте текст. Неверный id блока или шард — ошибка в запросе; тексты про хранилище означают, что блок вне того, что держит эта нода. Источник: validator/impl/liteserver.hpp, LiteQuery::fatal_error default code
-503	`timeout` Нода TON	Сработал собственный дедлайн ноды на запрос, пока она собирала ответ: тяжёлое доказательство, медленный диск или блок, который пришлось доставать из холодного хранилища.	Повторите один раз. Если конкретный запрос всегда истекает, сузьте его — меньше транзакций на страницу, более лёгкий метод. Источник: validator/impl/liteserver.cpp, LiteQuery::alarm
651	`block … is not applied` Нода TON	Блок у ноды есть, но он ещё не применён: нода догоняет сеть, либо запрошенный seqno опережает её состояние. Когда seqno опережает ноду, текст заканчивается на «(last known masterchain block: N)».	Подождите, пока нода догонит, и повторите. Если вычисляете seqno сами, не запрашивайте блоки новее, чем сообщает getMasterchainInfo. Источник: validator/manager.cpp, process_block_handle_for_litequery_error
651	`block … is not in db` Нода TON	Нода не получала этот блок: он новее того, что у неё есть, либо старше того, что она хранит.	Найдите существующий блок через lookupBlock по текущей информации мастерчейна; для старых блоков нужен архивный тариф. Источник: validator/manager.cpp, process_block_handle_for_litequery_error
651	`lt not in db` Нода TON	lookupBlock по логическому времени запросил lt, которое не покрывает ни один индекс блоков на этой ноде: оно старше хранилища ноды, либо блока с таким lt не существует.	Где возможно, запрашивайте по seqno или по utime; для lt в прошлом используйте архивный тариф. Источник: validator/db/archive-manager.cpp, ArchiveManager::get_block_by_lt
652	`timeout for adnl query …` C++-клиент	Слой ADNL-запросов C++-клиента (lite-client, tonlib) перестал ждать ответа. Библиотеки на Python, JavaScript и Go вместо этого кода бросают собственные ошибки таймаута.	Поднимите таймаут клиента выше окон шлюза 7 с / 20 с и проверьте сетевой путь. Если шлюз ответил 502, настоящая причина в нём. Источник: adnl/adnl-query.cpp, AdnlQuery::alarm
651	`not ready / conn not ready` C++-клиент	C++-клиент отправил запрос до завершения рукопожатия с liteserver или после обрыва соединения.	Дождитесь готовности соединения — библиотеки делают это сами — и переподключайтесь при закрытии простаивающего соединения: это нормально. Источник: adnl/adnl-ext-client.cpp, AdnlExtClientImpl::send_query

651 = ErrorCode::notready, 652 = ErrorCode::timeout — common/errorcode.h

Работает в браузере. То, что вы вставляете, не покидает эту страницу.

Как читать ошибку liteserver

На каждый запрос liteserver отвечает либо запрошенным объектом, либо liteServer.error с целочисленным code и текстом message. Шлюз TONNode использует тот же конверт для собственных отказов, поэтому ваша библиотека показывает их так же, как любую ошибку ноды: tonutils-go хранит код в ton.LSError, pytoniq бросает LiteServerError с .code и .message, а ton-lite-client — Error, в котором только текст.

Коды приходят из двух мест, и таблица помечает, откуда именно:

Коды шлюза — 400, 403, 429, 500, 502 — выдаёт шлюз TONNode, стоящий между вашим ADNL-соединением и нодой. Он сверяет метод с тарифом, применяет лимит скорости и потолок параллелизма и направляет запрос на лёгкую или архивную ноду. Эти строки повторяют главу 5 документации LiteServers.
Коды ноды приходят из софта ноды в ton-blockchain/ton. -400 — код по умолчанию, с которым отправляется текст ошибки LiteQuery, -503 timeout — собственный дедлайн ноды на запрос, а 651 и 652 — это ErrorCode::notready и ErrorCode::timeout из common/errorcode.h. Две строки порождает сам C++-клиент (lite-client, tonlib), а не сервер; библиотеки на других языках в тех же ситуациях бросают собственные исключения.

Самые важные

403 archive history is not included in this plan. Единственный сигнал, который имеет значение при обходе истории. Запросу понадобился блок, которого лёгкая нода уже не хранит — она держит около двух дней истории при текущей скорости блоков, это порядок величины, а не обещание, — а в тарифе нет архива. Повторять бессмысленно: либо добавьте архив в тариф, либо запросите более свежий блок. Глава 4 объясняет, где проходит граница, и содержит пробу, которая измеряет её для вашего ключа.

429 — три разных лимита. too many requests — лимит скорости на ключ, leaky bucket в единицах стоимости: обычное чтение стоит 5, полная страница getTransactions — до 16, целый блок — 50. too many concurrent requests for this key — потолок запросов в полёте: половина RPS тарифа, не меньше 8 и не больше 128. gateway is saturated — общий потолок в 256 запросов в полёте по всем клиентам. Первые два означают, что клиенту нужен темп; последний — что бэкенду тяжело, и правильный ответ — задержка перед повтором. В главе 7 есть таблица стоимости и примеры клиента с заданным темпом.

502 backend node timeout. Нода не ответила в окно шлюза: 7 с для лёгкой ноды, 20 с для архива. Установите собственный таймаут клиента выше этих значений; более короткий превращает настоящий 502 в локальный таймаут и теряет диагноз.

651 и семейство «not in db». block … is not applied, block … is not in db и lt not in db несут ErrorCode::notready. Все они означают, что у этой ноды нет готовым того, что вы запросили: она ещё догоняет сеть, блок опережает её состояние, либо блок или логическое время старше её хранилища. Свежий блок появится сам; для старого нужен архив.

Что повторять

429 повторяйте с задержкой, 502 — один раз сразу. 403 не повторяйте — ни один из вариантов не станет верным со второй попытки. -400 из обхода транзакций тоже не повторяйте: это граница, а не сбой. Для 651 повторите через мгновение запрос блока новее состояния ноды и перестаньте повторять запрос блока старше её хранилища.

Ошибки мемпул-стрима

Мемпул-стрим — другой протокол со своим списком ошибок: JSON-сообщения error и коды закрытия WebSocket вроде 4401 и 4429. Эта таблица его не охватывает.

Частые вопросы

Какие ошибки стоит повторять?: 429 — с задержкой, 502 — один раз сразу. 403 не повторяйте: ни один из вариантов не станет верным со второй попытки. -400 из обхода транзакций тоже не повторяйте — это граница, а не сбой. 651 означает, что нода отстаёт или блок вне её хранилища: для свежего блока подождите и повторите, для старого используйте архив.
Почему я получаю 403 на getTransactions, но не на getAccountState?: getAccountState читает текущее состояние, которое у лёгкой ноды есть всегда. Обход транзакций идёт назад во времени, и когда он выходит за окно лёгкой ноды примерно в два дня, шлюз направляет его на архивную ноду — а тариф без архива ею пользоваться не может. Текст 403 называет причину: archive history is not included in this plan.
В чём разница между 651 и -503?: 651 — это ErrorCode::notready в софте ноды: данные в принципе существуют, но у этой ноды они не готовы — блок ещё не применён или lt вне её базы. -503 timeout — собственный дедлайн ноды на запрос: данные были, но собрать ответ вовремя не удалось.
Почему моя библиотека показывает не ту ошибку, что в таблице?: Библиотеки по-разному оборачивают liteServer.error. tonutils-go хранит код в ton.LSError, pytoniq бросает LiteServerError с кодом и сообщением, а ton-lite-client — Error только с текстом. Если кода нет, сопоставляйте по тексту.

Приватный доступ к liteserverТарифы Litenode и Archive: запрашивайте сеть напрямую со своим ключом.Документация LiteServersВсе методы, лимиты, маршрутизация в архив и полная глава об ошибках.

Другие инструменты

Конвертер и валидатор TON-адресовRaw ↔ EQ ↔ UQ, mainnet и testnet, проверка контрольной суммы, пакетный режим.Конвертер nanoton ↔ GRAM (TON) и единиц жетоновGRAM ↔ nanoton с 9 знаками и суммы жетонов ↔ raw-единицы с любым decimals.Хеш TON-сообщения из BoCcell_hash, norm_hash по TEP-467 и sha256 любого BoC сообщения, hex и base64.