Лимиты Telegram Bot API на масштабе: где ломается и как не вылететь

Лимиты Telegram Bot API на масштабе: где ломается и как не вылететь

Коротко. Bot API позволяет примерно 1 сообщение в секунду в один чат, 30 сообщений в секунду на рассылку по разным чатам и около 20 сообщений в минуту в один канал или группу. Любой переход за лимит — это HTTP 429 c parameters.retry_after в секундах. Ваш код должен честно подождать, отложить остальное в очередь и не разгоняться залпами. Лимит на загрузку фото — 10 МБ при multipart-загрузке (5 МБ, если Telegram забирает фото по URL), на остальные файлы через публичный Bot API — 50 МБ.

Ведёте каналы и не хотите писать очередь руками? Посмотрите, как Autogram батчит посты под лимиты.

Что именно ограничивает Bot API

Photo by Brett Sayles on Pexels

Цифры Telegram опубликованы в Bot API FAQ про рассылку — их легко запомнить, но непросто соблюдать на масштабе:

Два лимита, которые стоит выучить наизусть: 20 сообщений в минуту в один канал (потолок редакционного потока) и 30 сообщений в секунду по разным чатам (потолок broadcast). Долгоживущие деплои первыми упираются в канальный лимит — там копится редакционный объём; broadcast-боты первыми бьются о межчатовый — рост аудитории незаметно проталкивает их за грань.

Это не все ограничения. Любая модификация состояния сообщения — editMessageText, deleteMessage, forwardMessage, copyMessage, setMessageReaction — считается в вашем бюджете отправок. У ботов inline-режима свой набор ограничений по латентности в answerInlineQuery, и они принудительно срабатывают по таймауту для пользователя, а не по 429 в ответе.

Как throttling работает на практике

Photo by RDNE Stock project on Pexels

Когда вы пересекаете лимит, Telegram возвращает HTTP 429 Too Many Requests с JSON-телом, в котором по референсу making-requests есть parameters.retry_after — целое число секунд. Реальный ответ выглядит так:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 17",
  "parameters": { "retry_after": 17 }
}

Правильная последовательность — три шага:

1. Остановите отправки только в пределах задушенной области. Если 429 пришёл по конкретному каналу — заморозьте записи в этот канал, а не весь worker pool.
2. Поспите retry_after секунд плюс небольшой jitter (200–500 мс). Без jitter все воркеры вернутся на одном такте и снова выбьют лимит.
3. Повторите тот же запрос. Модель идемпотентности Telegram предполагает, что упавший вызов не создал сообщение; успешный повтор не задублирует.

Большинство продакшен-библиотек это уже делают. aiogram и python-telegram-bot несут готовые обработчики RetryAfter; очередь pyrogram делает то же неявно. Чего они не делают — это предсказание лимита: они реагируют на 429 постфактум. На масштабе это стоит небольшой волны неудачных запросов на каждый всплеск, поэтому следующий раздел важен.

Стратегии батчинга, которые держат под капом

Три паттерна закрывают около 95% высоконагруженных Telegram-автоматизаций:

1. Token-bucket на каждый скоуп. Держите in-memory bucket на каждый chat ID и глобальный bucket на 30 токенов с пополнением раз в секунду. Не отправляйте, пока в bucket нет токена. Это полностью снимает 429-всплески. Bucket на Redis работает между worker pool; одно-процессному боту хватит asyncio-throttle или эквивалента.

2. Media groups вместо циклов. Вызов sendMediaGroup публикует до 10 фото или видео как единый альбом и считается одним запросом в канальном капе. Раскатка из 50 изображений падает с 50 сообщений (по сути невозможных — 2,5 минуты осторожного pacing) до 5 альбомов — спокойно под капом за минуту. Та же логика работает везде, где API позволяет свернуть N вызовов в один конверт.

3. Редакционное сглаживание. Если планировщик пытается отправить 100 канальных постов ровно в 09:00, никакая клиентская математика лимитов не спасёт — вы разобьётесь об edge Telegram до того, как bucket успеет принять решение. Растягивайте очередь на час на лету или заранее ставьте слоты в расписании. Двухминутный шаг между записями в один канал — безопасный дефолт; одна минута — пол, ниже которого начинается съедание канального лимита.

Архитектурные паттерны для масштаба

Photo by Keysi Estrada on Pexels

Когда один бот начинает отправлять больше ~100 тыс. сообщений в день, четыре архитектурных решения перестают быть опциональными:

• Один токен — одна исходящая очередь. Все отправки идут через единую FIFO-очередь на токен. Воркеров может быть много, но решение о throttle должно быть централизованным — распределённый token-bucket бьёт per-worker эвристику каждый раз.
• Self-hosted Bot API server для высокотрафичных аккаунтов. Telegram открыл TDLib-based local Bot API server. Он снимает 50-мегабайтный лимит на загрузку до 2 ГБ, уменьшает медиану latency и даёт полный контроль над connection pool и роутингом вебхуков.
• Разделяйте broadcast-ботов и интерактивных. Рассылки, бьющиеся о 30/сек, не должны делить токен с ботом, который отвечает на /start или обрабатывает inline-запросы. Задушенный токен — это задушенный токен — разделите и держите broadcast-токен как write-only worker.
• Наблюдаемость по retry_after. Считайте число 429 в минуту и скользящее среднее retry_after. Здоровый парк показывает плоскую линию у нуля; растущее среднее значит, что размер вашего token-bucket расходится с реальной ёмкостью Telegram, и платформа делает ту back-pressure, которую должен был делать ваш планировщик.

Если вы на управляемом планировщике — Autogram, например — большая часть этого живёт за API, и вы ничего не пишете. Прочитать раздел стоит хотя бы для того, чтобы когда клиент спросит «почему волна в 09:00 приземлилась в 09:04», у вас был правильный ответ, а не пожатие плечами.

Связанное чтение

• Массовая рассылка в Telegram: гид для агентств — как планировать высокообъёмные раскатки, не поднимая flood control.
• Автопостинг в Telegram без метки «Переслано» — маршрут через copyMessage, который считается в бюджете так же, как sendMessage.
• No-code автоматизация Telegram: Zapier vs Make vs ManyBot vs Autogram — как Zapier, Make и ManyBot обходят (или тихо прячут) потолок по лимитам.

FAQ

Что на самом деле значит «ошибка Telegram bot 429»?

Это значит, что ваш запрос пересёк один из лимитов Telegram в конкретном скоупе. В ответе есть parameters.retry_after в секундах — поспите столько и повторите тот же запрос. 429 — это load-shedding, а не окончательная ошибка.

Telegram flood control и лимиты Bot API — это одно и то же?

Нет. «Flood control» в клиенте и userbot-мире — это ограничения MTProto, эскалирующие до временных банов аккаунта. Лимиты Bot API мягче, скоупо-специфичны и сбрасываются за секунды. Конверт 429 c retry_after — особенность именно Bot API.

Сколько сообщений в секунду может отправить Telegram-бот?

До 30 между разными чатами (broadcast-скоуп) и примерно 1 в один чат. Запись в один канал — около 20 в минуту, то есть одно в 3 секунды на устойчивом графике.

Можно ли поднять лимит Telegram-бота?

Да, для рассылок. Функция Paid Broadcasts (включается через @BotFather) поднимает broadcast-лимит с 30 сообщений в секунду до 1 000 сообщений в секунду; каждое сообщение сверх бесплатных 30/сек стоит 0,1 Telegram Stars, а баланс бота должен быть не меньше 10 000 Stars. Не-broadcast лимиты (1/сек на чат, 20/мин на канал) остаются фиксированными. Self-hosted Bot API server поднимает лимит на загрузку файла до 2 ГБ, но не поднимает лимиты на отправку сообщений.

Как избежать попадания в лимит Bot API?

Запустите token-bucket на каждый скоуп (чат, канал, глобальный), батчите через sendMediaGroup где можно, сглаживайте редакционные очереди по часу и инструментируйте 429, чтобы видеть дрейф раньше пользователей.

Что будет, если игнорировать 429 retry_after?

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

sendMediaGroup считается одним сообщением или несколькими?

Как одно. Media group — один вызов Bot API независимо от того, сколько в нём вложений: 2 или 10. Именно поэтому это самый надёжный рычаг, чтобы держаться под канальным лимитом за минуту.

Итог

Лимиты Telegram Bot API мягкие, хорошо задокументированные и сбрасываются за секунды — но каждый продакшен-бот рано или поздно в них упирается, обычно в 09:00 в день запуска. Сделайте token-bucket, уважайте retry_after, батчите через media groups и выносите broadcast на отдельный токен. Autogram делает это за вас, так что единственная цифра, о которой придётся думать, — «сколько каналов».

Image credits

• Hero: Photo by Brett Sayles on Pexels.
• Inline #1: Photo by RDNE Stock project on Pexels.
• Inline #2: Photo by Keysi Estrada on Pexels.