Ограничения Telegram Bot API: лимиты запросов и очереди

Вы запустили бота в Telegram, и он внезапно перестал отвечать. Не потому что сломался, а потому что Telegram Bot API просто перестал его слушать. Это не ошибка - это лимиты. Каждый день тысячи разработчиков сталкиваются с тем, что их боты молчат, отвечают с задержкой или вообще блокируются. Причина? Превышение лимитов API. И если вы не знаете, как они работают, ваш бот может оказаться в тени - даже если он идеально написан.

Что такое лимиты Telegram Bot API?

Telegram Bot API - это интерфейс, через который ваш бот общается с серверами Telegram. Он не безграничный. Каждый бот получает строгие ограничения на количество запросов в секунду и в минуту. Эти лимиты не зависят от числа пользователей, размера канала или популярности бота. Даже если у вас 100 000 подписчиков, вы всё равно не можете слать 1000 сообщений в секунду.

Согласно официальной документации Telegram, основной лимит - 30 запросов в секунду на одного бота. Это средний порог, который работает для большинства сценариев. Но есть нюансы. Например, если вы отправляете сообщения с помощью метода sendMessage, то этот лимит применяется к каждому вызову. А если вы используете sendMediaGroup для отправки 10 фото за один вызов - это считается как один запрос, а не десять. Это важно, если вы планируете рассылать контент.

Какие лимиты есть на разные методы?

Не все методы API имеют одинаковые ограничения. Telegram не публикует полный список, но на практике вы сталкиваетесь с тремя группами:

• Высокий лимит (до 30 запросов/сек): sendMessage, editMessageText, getUpdates. Это основные методы, которые используются чаще всего.
• Средний лимит (до 10 запросов/сек): sendPhoto, sendDocument, sendVideo. Методы, связанные с медиа, имеют более жесткие ограничения из-за нагрузки на серверы.
• Низкий лимит (до 1 запрос/сек): setWebhook, deleteWebhook, deleteMessage. Эти методы редко используются, но если вы вызываете их слишком часто - получите ошибку 429.

Если вы используете бота для автоматической модерации чатов или массовой рассылки, вы быстро достигнете этих границ. Например, если ваш бот отвечает на 50 сообщений в минуту, и каждое сообщение требует 2 вызова API (получение текста + отправка ответа), вы уже близки к лимиту. А если у вас несколько ботов на одном сервере - вы рискуете превысить лимит для всего IP-адреса.

Что происходит, когда вы превышаете лимит?

Telegram не блокирует бота сразу. Он начинает смягчать ответы. Сначала вы получаете ошибку 429 Too Many Requests - это HTTP-статус, означающий, что вы перегрузили API. После этого Telegram вводит временную блокировку. Она может длиться от нескольких секунд до нескольких минут. Чем чаще вы превышаете лимит, тем дольше длится блокировка.

Вот что вы видите в логах:

{"ok":false,"error_code":429,"description":"Too Many Requests: retry after 10"}

Число после retry after - это время, через которое вы можете повторить запрос. Это не рекомендация. Это обязательство. Если вы игнорируете его и шлете запрос снова через 2 секунды - вы удвоите время блокировки. В худшем случае Telegram может временно отключить бота на 24-72 часа, особенно если вы отправляете спам или массовые сообщения без согласия пользователей.

Как управлять очередями запросов?

Чтобы не попасть в ловушку лимитов, нужно организовать очередь. Это не просто «подождать 1 секунду». Это система, которая автоматически откладывает запросы, если лимит исчерпан.

Вот как это работает на практике:

1. Когда ваш бот получает событие (например, сообщение от пользователя), он добавляет задачу в очередь.
2. Отдельный процесс (в фоне) берёт задачи из очереди и отправляет их в API с интервалом в 0.05-0.1 секунды - это безопасный темп, не превышающий 10-20 запросов в секунду.
3. Если приходит ошибка 429, процесс останавливается, ждёт указанное время и возобновляет работу.
4. Приоритеты: важные сообщения (например, уведомления о платежах) идут первыми. Рекламные или несрочные - откладываются.

Простой пример на Python с библиотекой aiogram:

from aiogram import Bot
from aiogram.types import Message

bot = Bot(token="YOUR_TOKEN")

@dp.message()
async def handle_message(message: Message):
    # Добавляем задачу в очередь, а не отправляем сразу
    await send_with_delay(message.chat.id, "Ответ на ваше сообщение")

async def send_with_delay(chat_id, text):
    while True:
        try:
            await bot.send_message(chat_id, text)
            break
        except aiogram.exceptions.TelegramRetryAfter as e:
            await asyncio.sleep(e.retry_after)

Такой подход гарантирует, что ваш бот никогда не превысит лимит, даже при пиковой нагрузке. Это стандарт для крупных ботов, таких как @CryptoBot или @NewsBot - они обрабатывают десятки тысяч запросов в день, не получая блокировок.

Почему нельзя просто ускорить бота?

Многие разработчики думают: «Если лимит 30 запросов в секунду, я просто запущу 10 серверов - и получу 300». Это не сработает. Telegram привязывает лимиты не к IP-адресу, а к токену бота. Даже если вы запустите 100 серверов с одним и тем же токеном - вы всё равно получите 30 запросов в секунду. Это защита от DDoS и спама.

Если вам нужно больше пропускной способности - у Telegram есть только один путь: использовать несколько ботов. Каждый бот имеет свой токен и свою очередь. Например, вы можете разделить логику: один бот отвечает на вопросы, второй обрабатывает оплаты, третий рассылает новости. Так вы получаете 30 × 3 = 90 запросов в секунду. Но это требует сложной архитектуры и синхронизации данных.

Как проверить, не превышаете ли вы лимиты?

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

• Количество ошибок 429 за минуту
• Среднее время ожидания при отправке сообщений
• Частоту повторных попыток

Если вы видите, что 10% запросов возвращают ошибку 429 - это красный флаг. Значит, вы работаете на грани. Нужно либо уменьшить частоту, либо добавить буферную очередь.

Используйте инструменты вроде Prometheus + Grafana, чтобы визуализировать запросы в реальном времени. Или просто сохраняйте логи в базу данных и стройте график по часам. Если в 14:00 вы видите всплеск ошибок - значит, в это время у вас пиковая нагрузка. Возможно, вы рассылаете уведомления в одно и то же время. Перенесите их на разное время - и проблема исчезнет.

Что делать, если бот уже заблокирован?

Если Telegram временно отключил вашего бота, не паникуйте. Не пытайтесь пересоздать его с новым токеном. Это не поможет. Telegram может заблокировать и новый токен, если он видит, что вы пытаетесь обойти ограничения.

Вместо этого:

1. Остановите все запросы к боту.
2. Подождите минимум 24 часа. Иногда блокировка снимается через 4-6 часов, но лучше перестраховаться.
3. Проверьте логи: что вызывало перегрузку? Спам? Массовая рассылка? Неправильная обработка ошибок?
4. Добавьте очередь и задержки.
5. Повторно запустите бота - и наблюдайте за первыми 100 запросами.

Если вы регулярно превышаете лимиты - это не техническая проблема. Это проблема дизайна. Бот не должен отвечать на всё сразу. Он должен отвечать на важное - быстро. На второстепенное - с задержкой. На спам - вообще не отвечать.

Практические советы, которые спасут ваш бот

• Не отправляйте сообщения без запроса пользователя. Telegram запрещает массовую рассылку без явного согласия. Даже если вы думаете, что это «полезные уведомления» - это нарушение.
• Используйте кэширование. Если бот часто отвечает одним и тем же текстом (например, инструкции), сохраняйте его в памяти или Redis. Не дергайте API для одинаковых ответов.
• Сжимайте медиа. Картинки 5 МБ - это тяжело. Сжимайте их до 1-2 МБ. Это уменьшает нагрузку на серверы и ускоряет обработку.
• Используйте Webhook вместо getUpdates. Webhook работает быстрее и стабильнее. Он не требует постоянных опросов сервера, что экономит запросы.
• Тестируйте под нагрузкой. Перед запуском бота в продакшене, сымитируйте 500 пользователей одновременно. Увидите, как он ведёт себя при пиковой нагрузке.

Бот - это не автоматический ответчик. Это сервис. И как любой сервис, он требует управления. Лимиты - не враги. Они защита. Для пользователей. Для Telegram. И для вас - чтобы ваш бот не упал в самый неподходящий момент.