Лимиты и ошибки

Лимиты в секунду

Каждый вызов относится к одному из трёх классов. Он расходует вашу квоту и лимит в секунду своего класса:

Класс	Вызовы	Ограничение
Блоковые запросы	`getnowblock`, `getblockbynum`, `getblockbyid`, `getblock` с `"detail": true`, `getblockbylimitnext`, `getblockbylatestnum`, `gettransactioninfobyblocknum` и их gRPC-аналоги	вызовов в секунду
Отправка транзакций	`broadcasttransaction`, `broadcasthex`, gRPC `BroadcastTransaction`	транзакций в секунду
Чтение	всё остальное	WU в секунду

Цифры зависят от тарифа — см. Тарифы и оплата. Лимиты принадлежат тарифу и общие для всех его эндпоинтов. Каждый лимит вмещает объём одной секунды. Например, при 30 WU/s сразу проходит до 30 WU, а затем лимит пополняется со скоростью 30 WU в секунду. Чтение пропускается, пока в лимите чтения осталось хоть сколько-то места, а его стоимость списывается после ответа: одно тяжёлое чтение может увести лимит ниже нуля, и следующие чтения ждут, пока он восполнится. Диапазон блоков возвращает не больше 10 блоков за вызов.

Формат ошибки

Отказ — это JSON с сообщением в Error и машиночитаемым code:

{"Error": "read limit (WU/s) exceeded", "code": "rate_read"}

Ориентируйтесь на code; сообщение может меняться. У отказа всегда есть code. У собственных ошибок ноды его нет: java-tron отвечает {"Error": "…"} без code, обычно со статусом 200, и такой ответ тарифицируется как любой другой — см. Единицы квоты. Отказы не тарифицируются и не несут X-Node-API-WU, кроме method_not_found, который несёт X-Node-API-WU: 0. Отказы 429 и 503 обычно несут Retry-After.

Коды отказов

Статус	`code`	Значение	Что делать
`400`	`key_conflict`	Два разных ключа в одном запросе	Передайте один ключ
`400`	`bad_request`	Запрос нельзя прочитать так, как прочитала бы его нода: больше 10 блоков в диапазоне, номер блока не целое число, параметр передан дважды, параметры блока переданы и в строке запроса, и в теле, в теле блокового метода есть неизвестные поля, `detail` не равен `true` или `false`	Исправьте запрос
`401`	`no_key`	В запросе нет ключа	Добавьте ключ
`401`	`unknown_key`	Такого ключа нет: опечатка, ключ удалён, это ключ REST API или он создан менее чем примерно 30 секунд назад	Проверьте ключ
`403`	`key_disabled`	Эндпоинт выключен — вами или при продлении из-за лимита эндпоинтов тарифа	Включите его в кабинете
`403`	`ip_not_allowed`	IP-адреса запроса нет в белом списке эндпоинта	Добавьте адрес
`403`	`no_plan`	У аккаунта нет тарифа Node API	Купите тариф
`403`	`plan_expired`	Подписка не активна: продление не оплачено, подписка закончилась или триал завершён	Пополните баланс или купите тариф
`403`	`account_blocked`	Доступ аккаунта к API приостановлен	Напишите в поддержку
`404`	`not_found`	Путь не относится к методам ноды: он вне `/wallet/` и `/walletsolidity/` (например, `/v1/...` или `/jsonrpc`) или в имени метода есть символы, кроме букв и цифр	Проверьте путь
`404`	`method_not_found`	У ноды нет такого метода. Имена методов чувствительны к регистру, как в java-tron: `getaccount`, но `getReward`. Стоит 0 WU	Проверьте написание
`405`	`method_not_allowed`	HTTP-метод, отличный от `GET` и `POST`	Используйте `GET` или `POST`
`413`	`body_too_large`	Тело запроса больше 512 KB	Отправьте тело поменьше
`429`	`rate_read`	Достигнут лимит чтения (WU в секунду)	Подождите `Retry-After`
`429`	`rate_block`	Достигнут лимит блоковых запросов (вызовов в секунду)	Подождите `Retry-After`
`429`	`rate_write`	Достигнут лимит отправки транзакций (транзакций в секунду)	Подождите `Retry-After`
`429`	`trials`	Общая пропускная способность всех триалов занята	Подождите `Retry-After`
`429`	`quota`	Квота израсходована на тарифе без перерасхода (триал)	Купите тариф
`429`	`overage_budget`	Квота израсходована, а баланс больше не покрывает перерасход	Пополните баланс
`502`	`node_error`	Нода не ответила или не ответила за 30 секунд	Повторите
`503`	`degraded`	Старый блок, его квитанции или диапазон блоков в режиме деградации	Повторите позже — см. ниже
`503`	`capacity`	Общая пропускная способность сервиса исчерпана	Подождите `Retry-After`
`503`	`capacity_write`	Общая пропускная способность сервиса для отправки транзакций исчерпана	Подождите `Retry-After`
`503`	`busy`	За 2 секунды не нашлось свободного соединения с нодой	Подождите `Retry-After`
`503`	`no_node`	Сейчас нет доступной ноды	Подождите `Retry-After`
`503`	`no_snapshot`	Сервис сейчас не может проверить ключи	Подождите `Retry-After`

По gRPC те же коды приходят в завершающих метаданных x-node-api-reason, а вместо HTTP-статуса — статус gRPC; см. gRPC.

Режим деградации

Когда наша основная нода для Node API недоступна или отстаёт от сети, сервис продолжает работать на резервной ноде. В это время:

вызовы с ответом несут заголовок X-Node-API-Mode: degraded (по gRPC — завершающие метаданные x-node-api-mode: degraded);
ваш лимит чтения в WU в секунду уменьшается вдвое; лимиты блоковых запросов и отправки транзакций не меняются;
свежие блоки — в пределах 20 от головы — и их квитанции отдаются как обычно, а более старые блоки, их квитанции и диапазоны блоков отклоняются с 503 degraded;
общая пропускная способность меньше, поэтому 503 capacity вероятнее.

Отправка транзакций никогда не урезается. Обычный режим возвращается сам — ничего делать не нужно. Если ваше приложение читает старые блоки, приостановите эту работу, пока заголовок присутствует, и возобновите, когда он исчезнет.

Повторы

429 rate_read, rate_block, rate_write, trials и любой 503: подождите столько секунд, сколько указано в Retry-After, затем повторите.
429 quota и 429 overage_budget: ожидание не поможет. Пополните баланс или смените тариф.
502 node_error: повторите. Повторно отправлять ту же подписанную транзакцию безопасно — сеть исполняет ID транзакции только один раз.
Остальные 4xx: исправьте запрос — повтор даст тот же ответ.

import time
import requests

NODE = "https://node.tronrental.com"
HEADERS = {"TRON-PRO-API-KEY": "<YOUR_KEY>"}
STOP = {"quota", "overage_budget"}  # ожидание не поможет

def node_call(method, body=None, attempts=5):
    for attempt in range(attempts):
        resp = requests.post(f"{NODE}/wallet/{method}", json=body or {}, headers=HEADERS)
        if resp.status_code in (429, 502, 503):
            try:
                code = resp.json().get("code")
            except ValueError:
                code = None  # не наш JSON, например страница ошибки прокси
            if code in STOP:
                raise RuntimeError(f"Node API: {code}")
            time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
            continue
        return resp
    raise RuntimeError("Node API: retries exhausted")

​Лимиты в секунду

​Формат ошибки

​Коды отказов

​Режим деградации

​Повторы

Лимиты в секунду

Формат ошибки

Коды отказов

Режим деградации

Повторы