Ошибки

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

Ошибки возвращаются в одной из трёх форм. Большинство эндпоинтов использует первую; две другие встречаются на конкретных путях и описаны здесь, чтобы ваш клиент не пропустил код ошибки, который ищет. Стандартная. Код code для программной обработки, вложенный в detail.error:

{
  "detail": {
    "error": {
      "code": "INSUFFICIENT_BALANCE",
      "message": "Insufficient balance. Required: 12.5 TRX, available: 3.1 TRX"
    }
  }
}

Лимит уровня аккаунта. Те же поля, но на верхнем уровне, без detail — этот ответ формируется до того, как запрос дойдёт до эндпоинта:

{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please try again later."}}

Плоская. Шаги подтверждения вывода кладут code рядом с detail, а в detail находится само сообщение:

{"detail":"Passkey verification required","code":"PASSKEY_REQUIRED"}

Код есть не в каждом ответе. Ошибки валидации запроса приходят в собственном формате фреймворка, где detail — массив ошибок по полям, а не строка; несколько внутренних проверок возвращают {"detail": "..."} с обычным текстом. При этом часть ответов 422 код всё же несёт, в стандартной форме, — например повторно использованный ключ идемпотентности.

Читайте код из первого поля, которое присутствует: detail.error.code, затем error.code, затем code. Если нет ни одного, ориентируйтесь на HTTP-статус. И никогда не считайте detail строкой: в стандартной форме это объект, а в ошибке валидации — массив.

HTTP-коды состояния

Код	Значение
`200`	Успех
`400`	Некорректный запрос — неверные параметры
`401`	Не авторизован — API-ключ отсутствует или недействителен
`402`	Требуется оплата — недостаточный баланс аккаунта
`403`	Запрещено — у ключа нет нужного разрешения, IP не в белом списке или требуется подтверждение
`404`	Не найдено
`409`	Конфликт — дублирующий запрос или конфликт ресурсов
`422`	Ошибка валидации — проверьте тело запроса
`429`	Превышен лимит запросов — см. Лимиты запросов
`500`	Ошибка сервера
`503`	Временно недоступно — повторите попытку позже

Основные коды ошибок

Возвращаются в стандартной форме, в поле detail.error.code:

Код	Статус	Описание
`INVALID_TOKEN`	`401`	API-ключ отсутствует, неизвестен или отключён
`ACCOUNT_BLOCKED`	`403`	Доступ к API для этого аккаунта заблокирован
`FORBIDDEN`	`403`	У ключа нет разрешения, которого требует эндпоинт, либо IP запроса отсутствует в белом списке ключа
`NODE_API_KEY_ONLY`	`403`	В этот API передан ключ Node API — он работает только на `node.tronrental.com`
`INSUFFICIENT_BALANCE`	`402`	Недостаточно средств на балансе для этой операции
`IDEMPOTENCY_KEY_REUSED`	`422`	Этот Idempotency-Key уже использован с другим телом запроса
`IDEMPOTENCY_KEY_TOO_LONG`	`422`	Idempotency-Key длиннее 64 символов
`INVALID_ADDRESS`	`400`	Некорректный TRON-адрес
`CONTRACT_ADDRESS_NOT_SUPPORTED`	`400`	Адрес назначения — смарт-контракт; TRON запрещает делегировать ресурсы на такие адреса
`INVALID_VOLUME`	`400`	Запрошенный объём вне допустимого диапазона
`INVALID_DURATION`	`400`	Длительность не входит в список допустимых значений
`ORDER_NOT_FOUND`	`404`	Заказ с таким ID не существует
`RATE_LIMIT_EXCEEDED`	`429`	Слишком много запросов — см. Лимиты запросов

У Node API (node.tronrental.com) свои коды ошибок в другом формате — см. Node API → Лимиты и ошибки.

INSUFFICIENT_BALANCE используется не везде. POST /api/v1/smart-mode/activate и POST /api/v1/transfer-packages/buy сообщают о том же условии статусом 400 с сообщением и без кода: {"detail":{"error":{"message":"Insufficient balance"}}}. На этих двух эндпоинтах не определяйте нехватку средств по одному лишь коду.

Коды автопополнения

Возвращаются в стандартной форме эндпоинтами автопополнения:

Код	Статус	Описание
`AUTOREFILL_ADDRESS_TAKEN`	`409`	У аккаунта уже есть правило для этого адреса и ресурса — вместо этого измените его
`AUTOREFILL_LIMIT_REACHED`	`409`	У аккаунта уже 20 правил для этого ресурса; лимит также передаётся в `error.limit`
`AUTOREFILL_IN_PROGRESS`	`409`	Прямо сейчас по правилу покупается пополнение — повторите изменение или удаление через минуту
`AUTOREFILL_DISABLED`	`503`	Автопополнение этого ресурса временно выключено; приходит только при создании правила. Правило не создано — повторите позже
`NOT_FOUND`	`404`	В аккаунте нет такого правила

Коды подтверждения вывода средств

POST /api/v1/account/withdrawal возвращает эти коды подтверждения в плоской форме, где code стоит рядом с detail. Остальные ошибки того же эндпоинта приходят в стандартной форме:

Код	Статус	Описание
`WITHDRAW_SCOPE_REQUIRED`	`403`	У API-ключа нет разрешения `withdraw`
`2FA_REQUIRED`	`403`	Нужно включить 2FA либо передать код
`IP_WHITELIST_REQUIRED`	`403`	Для вывода ключу требуется белый список IP
`PASSKEY_REQUIRED`	`403`	К аккаунту привязан passkey — вывод требует его
`INVALID_PASSKEY`	`403`	Челлендж passkey недействителен, истёк или не ваш
`INVALID_2FA_CODE`	`403`	Код 2FA или резервный код отклонён
`RATE_UNAVAILABLE`	`503`	Курс обмена временно недоступен — повторите попытку позже

Стратегия повторных попыток

Повторяйте ответы 5xx с экспоненциальной задержкой. Для 429 используйте заголовок Retry-After, если он есть, и сначала прочитайте тело — не всякий 429 является лимитом частоты (см. Лимиты запросов).

import time
import requests

def api_call_with_retry(url, **kwargs):
    for attempt in range(3):
        resp = requests.get(url, **kwargs)
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
            continue
        if resp.status_code >= 500:
            time.sleep(2 ** attempt)
            continue
        return resp
    raise Exception("Max retries exceeded")

Начало работы

Энергия TRON

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

HTTP-коды состояния

Основные коды ошибок

Коды автопополнения

Коды подтверждения вывода средств

Стратегия повторных попыток

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

​HTTP-коды состояния

​Основные коды ошибок

​Коды автопополнения

​Коды подтверждения вывода средств

​Стратегия повторных попыток

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

HTTP-коды состояния

Основные коды ошибок

Коды автопополнения

Коды подтверждения вывода средств

Стратегия повторных попыток