Личный кабинет

Главная → Документация → Лимит расхода и заголовки лимитов

Лимит расхода и заголовки лимитов

В личном кабинете можно задать потолок расхода по API: за день и за месяц, на весь аккаунт и на каждый дополнительный токен. Если ваша программа по ошибке начнёт слать запросы в цикле, она не потратит больше заданного. А в каждом ответе API приходят заголовки с остатком лимитов, чтобы программа могла притормозить сама.

Лимит за день и за месяцНа аккаунт и на токенОтказ без списания

Как задать лимит

Откройте в личном кабинете раздел «Токены», блок «Лимит расхода по API». Укажите сумму в рублях: «не больше в день» и «не больше в месяц». Можно задать только одно из двух. Пустое поле означает, что лимита нет.

Лимит дополнительного токена задаётся там же, в форме токена: при создании или по кнопке «Изменить». Это удобно для подрядчика или тестовой программы: дайте токену небольшой лимит, и он не сможет потратить больше.

Изменение действует со следующего запроса. Лимит по умолчанию не задан: пока вы его не поставили, ничего не меняется.

Что входит в расход

ЗапросыСчитаются
Запросы по API с основным токеномда, в расход аккаунта
Запросы по API с дополнительным токеномда, в расход аккаунта и в расход этого токена
Блоки сводного отчётада, каждый блок отдельно; если отчёт создан с дополнительным токеном, то и в расход токена
Проверки в личном кабинете: ручные, пакетные, мониторингнет, лимит на них не действует
Бесплатные ответы: «не найдено», ошибка, тестовые значениянет, считаются только списания

Расход за день обнуляется в полночь по московскому времени, расход за месяц считается с первого числа. Точное время до сброса приходит в заголовке Retry-After ответа с отказом.

Что происходит, когда лимит достигнут

Запрос не выполняется и не списывается. Ответ: HTTP 429, код SPEND_LIMIT_DAY или SPEND_LIMIT_MONTH, заголовок Retry-After с числом секунд до сброса лимита.

HTTP/1.1 429 Too Many Requests
Retry-After: 30412
X-Spend-Limit-Day: 500
X-Spend-Remaining-Day: 0

{
  "success": 0,
  "error": "Достигнут лимит расхода аккаунта за день: 500 ₽. Запрос не выполнен и не списан. Запросы снова пойдут после полуночи. Лимит меняется в личном кабинете: раздел «Токены».",
  "code": "SPEND_LIMIT_DAY"
}
Запрос при достигнутом лимитеЧто будет
Любой платный метод429 SPEND_LIMIT_DAY или SPEND_LIMIT_MONTH, без списания
Новый сводный отчётОтчёт не создаётся: тот же ответ 429
Отчёт, который уже выполняетсяБлоки, до которых дошла очередь после достижения лимита, завершаются ошибкой SPEND_LIMIT_DAY или SPEND_LIMIT_MONTH без списания. Выполненные блоки остаются в отчёте
Готовый отчёт по номеру, смета отчёта (dry_run), шаблоныРаботают
Баланс, статистика, тестовые значенияРаботают
Повтор уже выполненного запроса с тем же Idempotency-KeyСохранённый ответ, как обычно
Опрос уже созданной задачи (параметр task)Работает: результат начатой проверки не теряется

Лимит сверяется перед запросом, а стоимость запроса известна только после него. Поэтому расход может превысить лимит на стоимость последнего запроса и тех запросов, которые выполнялись одновременно с ним.

Если заданы лимит аккаунта и лимит токена, запрос с этим токеном проходит, только когда не достигнут ни один из них. В тексте ошибки сказано, какой лимит сработал: аккаунта или токена.

Уведомление о достигнутом лимите

Когда лимит достигнут в первый раз за период, вы получаете письмо на адрес аккаунта, сообщение в Telegram (если бот подключён) и событие limit.reached на вебхук (если оно отмечено в разделе «Вебхук»). Одно уведомление на период: за день или за месяц.

{
  "event": "limit.reached",
  "delivery_id": "d_5c1e0f3a9b7d2e44",
  "created_at": "2026-11-11T15:32:10+03:00",
  "limit": {
    "scope": "account",
    "token": null,
    "period": "day",
    "period_key": "2026-11-11",
    "amount": 500,
    "spent": 503.5,
    "code": "SPEND_LIMIT_DAY"
  }
}
ПолеЗначение
scopeaccount - лимит аккаунта, token - лимит дополнительного токена
tokenназвание токена или null для аккаунта
period, period_keyday и дата либо month и месяц
amount, spentлимит и расход на момент отказа, в рублях
codeкод, который получают запросы: SPEND_LIMIT_DAY или SPEND_LIMIT_MONTH

Заголовки лимитов в каждом ответе

Заголовки приходят в ответах на запросы по API. По ним программа видит, сколько запросов и денег осталось до ограничения, и может сбавить темп заранее, не дожидаясь отказа.

ЗаголовокЗначение
X-RateLimit-Limitсколько запросов в минуту разрешено вашему аккаунту
X-RateLimit-Remainingсколько запросов осталось в текущей минуте
X-RateLimit-Resetчерез сколько секунд освободится место. Минута скользящая: считаются запросы за последние 60 секунд
X-Spend-Limit-Day, X-Spend-Remaining-Dayлимит расхода за день и остаток, в рублях. Приходят, если лимит за день задан
X-Spend-Limit-Month, X-Spend-Remaining-Monthто же за месяц. Приходят, если лимит за месяц задан
Retry-Afterв ответе 429: через сколько секунд повторить запрос
HTTP/1.1 200 OK
X-Request-Id: 1840233
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 42
X-Spend-Limit-Day: 500
X-Spend-Remaining-Day: 131.5

Если у запроса с дополнительным токеном заданы и лимит токена, и лимит аккаунта, в заголовках X-Spend приходит тот из них, до которого осталось меньше.

Как пользоваться заголовками

Коды ошибок

КодHTTPЗначение
SPEND_LIMIT_DAY429достигнут лимит расхода за день (аккаунта или токена). Запрос не списан
SPEND_LIMIT_MONTH429достигнут лимит расхода за месяц. Запрос не списан
RATE_LIMIT429превышено число запросов в минуту. Запрос не списан, повторите через Retry-After секунд

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

Лимит достигнут, а проверки нужны сейчас. Увеличьте лимит в разделе «Токены»: новое значение действует со следующего запроса. Проверки в самом кабинете лимитом не ограничены.

Считается ли в расход ответ «не найдено»? Нет. В расход идут только списания: то же, что вы видите в блоке billing ответа.

Почему расход чуть больше лимита? Лимит сверяется до запроса. Последний запрос, который прошёл проверку, выполняется и списывается целиком, даже если после него расход стал больше лимита.

Нужно ли менять программу? Нет. Пока лимит не задан, ответы прежние, добавились только заголовки. Если лимит задан, научите программу не повторять запрос после кода SPEND_LIMIT_DAY или SPEND_LIMIT_MONTH.