What FLOOD_WAIT means
FLOOD_WAIT_X is a Telegram server response with code 420: the account made too many similar requests in a short time, and the server asks it to wait X seconds before repeating the action. The official error list puts it as "Please wait X seconds before repeating the action".
It's not a ban and not a spam block. The account works; one specific action is temporarily unavailable. Any API method can return this error — sending a message, joining a chat, resolving a username, loading a member list.
Apps and bots hit it most often, because they send requests faster than a person can.
Similar errors: FLOOD_PREMIUM_WAIT, SLOWMODE_WAIT, PEER_FLOOD
The names look alike, but they mean different things:
| Error | Meaning | What to do |
|---|---|---|
| FLOOD_WAIT_X | requests are too frequent | wait X seconds |
| FLOOD_PREMIUM_WAIT_X | file transfer speed is limited for non-Premium accounts | wait X seconds and continue |
| SLOWMODE_WAIT_X | the chat has slow mode on | wait — it's a chat setting, not your account |
| PEER_FLOOD | the account was reported | check your status in @SpamBot |
| PHONE_NUMBER_FLOOD | too many login attempts for this number | wait and don't request a new code |
The most dangerous mix-up is PEER_FLOOD versus FLOOD_WAIT. The former isn't a timer but a limit after reports: waiting won't clear it. See the guide on spam blocks and frozen accounts.
How long to wait
Exactly as long as X says. The number comes inside the error and ranges from a few seconds to many hours. Telegram doesn't publish how it's calculated and doesn't promise the next FLOOD_WAIT will be the same.
A practical rule:
- seconds or minutes — wait and repeat the same action;
- hours — stop this kind of action on the account until the term ends and hand the work to other accounts;
- it keeps coming back — the account is working too hard, slow down.
For bots on the Bot API the same situation shows up as HTTP 429 with a retry_after field — same meaning.
How libraries handle it
Popular libraries can sit out a short FLOOD_WAIT on their own and raise an error when the wait exceeds a threshold:
| Library | Setting | Default |
|---|---|---|
| Telethon | flood_sleep_threshold | 60 seconds |
| Pyrogram | sleep_threshold | 10 seconds |
| GramJS | floodSleepThreshold | 60 seconds |
| grammY (bots) | auto-retry plugin | waits retry_after and retries |
Keep the threshold small. If the library silently sleeps for an hour, your app looks frozen and you never learn the account hit a limit.
Why you shouldn't retry right away
The wait is mandatory: the server tells you exactly how long. A request before the time is up returns the same error. The grammY docs put it briefly: hitting rate limits doesn't get you banned, ignoring them does.
A run of FLOOD_WAITs in a row means the account is working at the edge. The next step is often a limit that waiting won't fix. So it makes sense not only to wait, but to reduce the load on the account.
What makes FLOOD_WAIT more frequent
Nobody knows the exact limits — the authors of Telethon, Pyrogram and grammY say so directly. But FLOOD_WAIT is known to come more often with:
- many identical requests in a row without pauses — for example, resolving dozens of usernames per minute;
- new accounts and accounts on virtual numbers;
- several apps working with one account at once — each thinks it's within the norm, but the server sees the total;
- the same session open in two places at once, which also causes
AUTH_KEY_DUPLICATED.
Which limits Telegram publishes officially and which are known only from observation — see the guide on Telegram limits.
Limits for bots
For bots, Telegram publishes guidelines in the developer FAQ:
- no more than one message per second to a single chat;
- no more than 20 messages per minute to one group;
- about 30 messages per second for bulk notifications to the bot's subscribers.
Regular accounts, as opposed to bots, have no such figures. There, limits show up in server responses, and FLOOD_WAIT is the main one.