Что означает FLOOD_WAIT
FLOOD_WAIT_X — ответ сервера Telegram с кодом 420: аккаунт сделал слишком много одинаковых запросов за короткое время, и сервер просит подождать X секунд, прежде чем повторить действие. В официальном списке ошибок текст звучит так: «Please wait X seconds before repeating the action».
Это не бан и не спамблок. Аккаунт работает, просто конкретное действие временно недоступно. Такую ошибку может вернуть любой метод API — отправка сообщения, вступление в чат, поиск по username, загрузка списка участников.
Чаще всего с ним сталкиваются программы и боты: они делают запросы быстрее человека.
Похожие ошибки: FLOOD_PREMIUM_WAIT, SLOWMODE_WAIT, PEER_FLOOD
Названия похожи, но смысл разный:
| Ошибка | Что значит | Что делать |
|---|---|---|
| FLOOD_WAIT_X | слишком частые запросы | подождать X секунд |
| FLOOD_PREMIUM_WAIT_X | скорость загрузки файлов ограничена для аккаунта без Premium | подождать X секунд и продолжить |
| SLOWMODE_WAIT_X | в чате включён медленный режим | подождать — это настройка чата, а не вашего аккаунта |
| PEER_FLOOD | на аккаунт жаловались | проверить статус в @SpamBot |
| PHONE_NUMBER_FLOOD | слишком много попыток входа по номеру | подождать и не запрашивать код снова |
Самая опасная путаница — PEER_FLOOD и FLOOD_WAIT. Первое — не таймер, а ограничение после жалоб: ожиданием его не снять. О нём — в гайде про спамблок и заморозку.
Сколько ждать
Ровно столько, сколько указано в X. Число приходит в самой ошибке и бывает от нескольких секунд до многих часов. Telegram не публикует формулу, по которой его считает, и не обещает, что следующий FLOOD_WAIT будет таким же.
Практическое правило:
- секунды и минуты — подождать и повторить то же действие;
- часы — остановить этот тип действий на аккаунте до конца срока, а работу передать другим аккаунтам;
- повторяется раз за разом — аккаунт работает слишком плотно, снизьте темп.
Для ботов на Bot API та же ситуация выглядит как HTTP 429 с полем retry_after — смысл тот же.
Как ошибку обрабатывают библиотеки
Популярные библиотеки умеют сами переждать короткий FLOOD_WAIT и выбрасывают ошибку, если ждать дольше порога:
| Библиотека | Настройка | По умолчанию |
|---|---|---|
| Telethon | flood_sleep_threshold | 60 секунд |
| Pyrogram | sleep_threshold | 10 секунд |
| GramJS | floodSleepThreshold | 60 секунд |
| grammY (боты) | плагин auto-retry | ждёт retry_after и повторяет |
Порог стоит держать небольшим. Если библиотека молча спит час, программа выглядит зависшей, а вы не узнаете, что аккаунт упёрся в лимит.
Почему нельзя повторять сразу
Ожидание обязательно: сервер прямо говорит, сколько ждать. Запрос до истечения срока снова вернёт ту же ошибку. Документация grammY формулирует коротко: за упор в лимит не банят, банят за то, что лимит игнорируют.
Серия FLOOD_WAIT подряд — сигнал, что аккаунт работает на пределе. Следующим шагом бывает уже ограничение, которое ожиданием не проходит. Поэтому разумно не только ждать, но и снижать нагрузку на аккаунт.
Что повышает частоту FLOOD_WAIT
Точных лимитов не знает никто — это прямо пишут авторы Telethon, Pyrogram и grammY. Но известно, что чаще упираются в FLOOD_WAIT:
- много одинаковых запросов подряд без пауз — например, поиск десятков username за минуту;
- новые аккаунты и аккаунты на виртуальных номерах;
- несколько программ, работающих с одним аккаунтом одновременно — каждая думает, что укладывается в норму, а сервер видит сумму;
- одна и та же сессия, открытая в двух местах сразу — это даёт ещё и ошибку
AUTH_KEY_DUPLICATED.
Какие лимиты Telegram публикует официально, а какие известны только по наблюдениям — в гайде о лимитах Telegram.
Лимиты для ботов
Для ботов Telegram публикует ориентиры в FAQ для разработчиков:
- не больше одного сообщения в секунду в один чат;
- не больше 20 сообщений в минуту в одну группу;
- около 30 сообщений в секунду при массовой рассылке подписчикам бота.
Для обычных аккаунтов, а не ботов, таких цифр нет. Там лимиты подбираются по ответам сервера, и FLOOD_WAIT — главный из них.