Лимиты запросов

К каждому запросу применяются два лимита: лимит уровня аккаунта, действующий почти на весь API, и, на нескольких эндпоинтах, более строгий лимит самого эндпоинта. Вы упрётесь в тот, который ниже.

Лимит уровня аккаунта

Считается по аккаунту в фиксированном минутном окне. Все API-ключи одного аккаунта делят общий бюджет — создание новых ключей лимит не повышает.

Кто вы	Лимит по умолчанию
Аккаунт с прошлой покупкой или подпиской либо с балансом от 10 TRX	1000 запросов/минута
Любой другой аккаунт с авторизацией	300 запросов/минута
Запросы без авторизации	60 запросов/минута на IP-адрес
Опрос `GET /api/v1/invoices/{invoice_id}` без авторизации	180 запросов/минута на IP-адрес

Бюджеты без авторизации считаются отдельно для каждой группы эндпоинтов — цены, статус инвойса, запросы по адресу, аутентификация и всё остальное, — поэтому опрос цен не расходует бюджет остальных запросов. Это значения по умолчанию. Если вашей интеграции нужен более высокий потолок, мы поднимем его для вашего аккаунта — напишите нам в Telegram.

Окно фиксированное, а не скользящее: счётчик обнуляется в начале каждой минуты. Не стройте всплеск вокруг этой границы. Мешают два независимых механизма. Перед API стоит краевой лимит примерно в 50 запросов в секунду на IP-адрес, и он отвечает 503 с HTML-телом, а не JSON-ошибкой. А аккаунт, державшийся сверх лимита три минуты подряд, получает лимит вдвое меньше на следующие десять минут; ещё три такие минуты — полная блокировка на тридцать, с Retry-After: 1800. Аккаунты с ярусом 1000/минута этой лестнице не подвержены.

Эндпоинты со своим, более строгим лимитом

Эндпоинт	Лимит	Считается по
`POST /api/v1/invoices`	10 запросов/минута	IP-адресу
`POST /api/v1/account/withdrawal`	5 с после вывода, созданного с `Idempotency-Key`, 60 с — после вывода без него	аккаунту
`POST /api/v1/energy/auto-refill`	10 запросов/минута	аккаунту
`POST /api/v1/bandwidth/auto-refill`	10 запросов/минута	аккаунту

Обратите внимание: POST /api/v1/invoices считается по IP-адресу, а не по аккаунту. Если несколько ваших клиентов отправляют запросы с одного исходящего IP, они делят общий бюджет в 10 запросов в минуту. У эндпоинтов покупки — POST /api/v1/energy/buy, POST /api/v1/energy/activate, POST /api/v1/bandwidth/buy и POST /api/v1/bandwidth/rentals — есть более старый бюджет в 1000 запросов в минуту, считаемый по IP-адресу (оба bandwidth-эндпоинта делят один бюджет). Для одного аккаунта он никогда не оказывается связывающим, но клиенты за общим исходящим IP делят его между собой. Эндпоинты управления вебхуками (/api/v1/webhooks/...) лимитом уровня аккаунта не покрыты. У всех остальных задокументированных эндпоинтов своего лимита нет — к ним применяется только лимит уровня аккаунта.

Как выглядит ответ 429

Тело зависит от того, в какой лимит вы упёрлись. Форм три, поэтому разбирайте ответ защитно, а не в расчёте на одну из них. Лимит уровня аккаунта. Ответ содержит заголовок Retry-After с числом секунд ожидания:

HTTP/1.1 429 Too Many Requests
Retry-After: 37

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

Лимит эндпоинта, например на POST /api/v1/invoices. Заголовка Retry-After нет, окно — одна минута:

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

POST /api/v1/account/withdrawal. Текстовое поле detail с остатком секунд и без кода ошибки:

{"detail":"Rate limit: try again in 42s"}

Ответ 429, который повторами не лечится

POST /api/v1/invoices отвечает 429 ещё и тогда, когда у вас уже слишком много неоплаченных инвойсов — не более 3 на IP-адрес и не более 5 на аккаунт. Лимит на IP действует и для авторизованных запросов, поэтому обычно вы упираетесь именно в него:

{"detail":"Too many pending invoices (max 3)"}

Это ограничение на число открытых инвойсов, а не лимит частоты, и само по себе ожидание его не снимает. Оплатите один из неоплаченных инвойсов или дождитесь его истечения, прежде чем создавать следующий. Тот же эндпоинт отдаёт 429 и на посторонние временные сбои — например {"detail":"Energy price unavailable"}. Прочитайте сообщение, прежде чем решать, как реагировать.

Повторные попытки

Если в ответе есть заголовок Retry-After, ждите ровно указанное число секунд.
Иначе используйте экспоненциальную задержку, начиная с одной секунды.
Никогда не повторяйте запрос немедленно.
Прочитайте тело перед повтором: Too many pending invoices требует другого действия, а не более долгого ожидания.

import time
import requests

def post_with_retry(url, **kwargs):
    for attempt in range(3):
        resp = requests.post(url, **kwargs)
        if resp.status_code == 429:
            body = resp.text
            if "pending invoices" in body:
                raise RuntimeError(body)  # ожидание здесь не поможет
            delay = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(delay)
            continue
        return resp
    raise RuntimeError("Max retries exceeded")

Нужны более высокие лимиты?

Свяжитесь с нами через Telegram для настройки индивидуальных лимитов для высоконагруженных интеграций.