Главная → Документация → Лимит расхода и заголовки лимитов
Лимит расхода и заголовки лимитов
В личном кабинете можно задать потолок расхода по 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"
}
}
| Поле | Значение |
|---|---|
scope | account - лимит аккаунта, token - лимит дополнительного токена |
token | название токена или null для аккаунта |
period, period_key | day и дата либо 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 приходит тот из них, до которого осталось меньше.
Как пользоваться заголовками
- Не упирайтесь в отказ. Когда
X-RateLimit-Remainingблизок к нулю, подождитеX-RateLimit-Resetсекунд перед следующим запросом. - Получили 429: ждите
Retry-After. Повтор раньше этого времени снова получит отказ. У лимита расхода это время до конца суток или месяца: повторять в цикле бессмысленно, нужно увеличить лимит в кабинете или дождаться сброса. - Следите за деньгами. По
X-Spend-Remaining-Dayвидно, сколько осталось до потолка: можно заранее предупредить оператора или перенести неважные проверки на завтра.
Коды ошибок
| Код | HTTP | Значение |
|---|---|---|
SPEND_LIMIT_DAY | 429 | достигнут лимит расхода за день (аккаунта или токена). Запрос не списан |
SPEND_LIMIT_MONTH | 429 | достигнут лимит расхода за месяц. Запрос не списан |
RATE_LIMIT | 429 | превышено число запросов в минуту. Запрос не списан, повторите через Retry-After секунд |
Частые вопросы
Лимит достигнут, а проверки нужны сейчас. Увеличьте лимит в разделе «Токены»: новое значение действует со следующего запроса. Проверки в самом кабинете лимитом не ограничены.
Считается ли в расход ответ «не найдено»? Нет. В расход идут только списания: то же, что вы видите в блоке billing ответа.
Почему расход чуть больше лимита? Лимит сверяется до запроса. Последний запрос, который прошёл проверку, выполняется и списывается целиком, даже если после него расход стал больше лимита.
Нужно ли менять программу? Нет. Пока лимит не задан, ответы прежние, добавились только заголовки. Если лимит задан, научите программу не повторять запрос после кода SPEND_LIMIT_DAY или SPEND_LIMIT_MONTH.