Лимиты и кредиты

Лимит в минуту

У ключа — лимит вызовов в минуту. Окно — календарная минута UTC; остаток и время до новой минуты приходят в заголовках каждого ответа:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 41

Лимит выбран — 429 too_often с retry_after (и заголовком Retry-After). Лимит ключа не выше лимита тарифа. GET /v1/me в лимит не считается.

Квоты

Суточная квота ключа (если задана) — X-Quota-Limit и X-Quota-Remaining; выбрана — 429 quota_exceeded до конца суток UTC.
Задачи одновременно — не больше, чем позволяет тариф (в очереди и в работе вместе); сверх — 429 quota_exceeded, пока какая-то задача не закончится.
Каналы в подписках — уникальных каналов во всех подписках организации не больше лимита тарифа; один и тот же канал в двух подписках считается один раз. Сверх — 402 plan_limit.

Кредиты

Платите за полученные записи. Пустой ответ, любая ошибка и повтор с тем же Idempotency-Key не списываются. Служебные пути бесплатны: /v1/me, /v1/usage, списки и карточки задач, файл результата (его оплатила задача), управление подписками, оценка задачи.

Кредиты дробные: запись стоит от 0,5 кредита. Сумма вызова или задачи — цена × число записей, округлённая вверх до сотой один раз на итоге. В ответах API кредиты — числом: 0.5, 1234.25, 30000.

путь	единица	кредитов
`POST /v1/tg/posts`	пост канала	0,5 за запись
`POST /v1/tg/messages`	сообщение чата	1 за запись
`POST /v1/tg/resolve`	карточка канала или чата	1,5 за запись
`POST /v1/tg/full`	карточка канала или чата	1,5 за запись
`POST /v1/tg/media`	медиа	1 за начатый МБ
`POST /v1/vk/wall.get`	запись или комментарий	0,5 за запись
`POST /v1/vk/wall.getById`	запись или комментарий	0,5 за запись
`POST /v1/vk/wall.getComments`	запись или комментарий	0,5 за запись
`POST /v1/vk/wall.getReposts`	запись или комментарий	0,5 за запись
`POST /v1/vk/wall.search`	найденный пост	1 за запись, не меньше 10 за запрос, если нашлось
`POST /v1/vk/newsfeed.search`	найденный пост	1 за запись, не меньше 10 за запрос, если нашлось
`POST /v1/vk/groups.getById`	карточка сообщества	1 за запись
`POST /v1/vk/groups.search`	карточка сообщества	1 за запись
`GET /v1/vk/page`	страница vk.com	1 за вызов
`POST /v1/vk/batch`	запись или комментарий	0,5 за запись
прочие методы ВКонтакте на чтение	запись	0,5 за запись
`POST /v1/jobs`	по шаблону сбора (таблица)	за итог задачи

Задача списывается один раз, после исполнения, за собранные записи; сумма — в result_summary.credits. Медиа задачи (media: true) — ещё 1 кредит за каждый начатый мегабайт. Поток списывается в конце — за отданные записи.

Кредиты расходуются по порядку: сначала кредиты тарифа за месяц (сгорают в конце месяца), потом дополнительные (купленные пакетом, не сгорают), потом перерасход — только если он включён в кабинете и в пределах потолка в рублях. Остаток — GET /v1/me → billing.credits; на 50, 80 и 100 % бюджета месяца — уведомление в кабинете.

Потолок расходов

Больше, чем оплачивает остаток, не отдаётся: limit у постов и сообщений урезается до остатка, max_bytes у медиа — до остатка в мегабайтах, задача без limit получает его по остатку. Цену заранее показывает POST /v1/jobs/estimate: «от–до», остаток и хватит ли его.

`402 payment_required` и режим чтения

code	что случилось	что делать
`credits_exhausted`	кредиты месяца и дополнительные кончились, перерасход выключен или его потолок выбран	пополнить баланс пакетом, включить перерасход или дождаться нового месяца
`trial_ended`	тестовый период закончился	выбрать тариф и оплатить его в кабинете («Тариф и оплата»)
`read_only`	счёт на продление не оплачен после 7 льготных дней	оплатить счёт
`subscription_cancelled`	подписка закрыта	оформить тариф заново; данные сохраняются
`no_subscription`	у организации нет тарифа	выбрать тариф
`not_in_plan`	возможности нет в тарифе (например, медиа на тестовом периоде)	сменить тариф
`plan_limit`	лимит тарифа: каналов в подписках больше, чем разрешено	убрать лишние каналы или сменить тариф

В режиме чтения и при нуле кредитов работает всё, что не собирает новых данных: GET /v1/usage, GET /v1/me, список и карточки задач, их файлы, отмена задачи, оценка, чтение и конец подписок, файл медиа по уже выданной ссылке. Подписки на это время встают на паузу и продолжают работу сами после оплаты.