Що означає 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 — головна з них.