Telegram FLOOD_WAIT Explained for Admins and Bot Builders

FLOOD_WAIT is Telegram telling a client that it made too many requests of one kind too quickly, and that it must wait a stated number of seconds before trying again. Bots see the same idea as a "429 Too Many Requests" error with a retry time. The fix is never to retry harder: wait the time Telegram gives you, then slow down so it does not happen again.

This guide is for two readers. Channel and group admins who meet "please wait" or "too many attempts" messages in the app, and developers whose bots or scripts receive flood errors. It explains what the errors are, what triggers them, the limits Telegram does document, and how to design around them.

What a flood error is

Telegram protects its servers and its users from spam by limiting how often an account or bot can perform each action. When a client goes over a limit, Telegram refuses the request and says how long to wait.

There is no single global limit. Each action has its own, and Telegram does not publish most of them. Limits can depend on:

• The action. Sending a message, joining a group, resolving a username, adding members and changing profile details all have separate limits.
• The target. Sending to one chat many times is treated differently from sending once to many chats.
• The account's history. New accounts and accounts with spam reports tend to meet limits sooner than long-standing ones.
• Recent behaviour. Hitting a limit repeatedly can make the next wait longer, so retrying in a tight loop works against you.

Because most limits are not published, the right approach is not to find the exact number and run just below it. It is to handle the error gracefully and leave a margin.

The forms the error takes

Flood limits show up differently depending on how you use Telegram.

In the Telegram apps

Normal users and admins never see the word FLOOD_WAIT. Instead the app shows a message such as "Too many attempts, please try again later", or a notice that you must wait some minutes before repeating an action. Sometimes it says nothing and the action simply fails. Our guide to Telegram's "too many attempts" message covers the login and code side of this in detail.

In the Bot API

Bots built on the Bot API receive an HTTP error with code 429 and the description "Too Many Requests". The response includes a parameters object with a retry_after field: the number of seconds to wait before repeating the request. This is the official way to learn the wait time, and your code should read it rather than guessing.

In MTProto libraries

Developers who use Telegram's own protocol, through a library, receive error code 420 with names like FLOOD_WAIT_X, where X is the number of seconds to wait. Related errors you may meet:

• FLOOD_PREMIUM_WAIT_X. A wait linked to actions where Telegram Premium accounts get higher limits, reported mainly around file transfers.
• SLOWMODE_WAIT_X. Not a global flood limit, but the group's slow mode: the admin has set a minimum gap between messages from each member. See slow mode and member restrictions.

A related error that is not a wait: PEER_FLOOD

PEER_FLOOD looks similar but means something different. It usually signals that the account has been limited for behaviour that looks like spam, such as messaging many strangers. Waiting a few seconds does not fix it. A user account in this state can check its status with Telegram's official @SpamBot. Treat PEER_FLOOD as a warning to stop the activity, not as a timer.

What Telegram documents for bots

Telegram's Bots FAQ gives rough guidance for bot sending rates. In its own words the figures are approximate, but they are the best official reference:

• In a single chat, avoid sending more than about one message per second. Short bursts may pass, but sustained sending above that leads to 429 errors.
• In a group, a bot should not send more than about 20 messages per minute.
• For bulk notifications to many users, the free limit is roughly 30 messages per second.
• Paid broadcasts can be enabled for a bot in @BotFather. Telegram says this raises the bulk sending limit substantially, up to 1,000 messages per second, with a cost in Telegram Stars for messages above the free amount. Check the current terms in @BotFather and Telegram's bot documentation before relying on it.

Treat these as ceilings, not targets. Running exactly at the limit leaves no room for retries, edits or replies.

What triggers flood limits for admins

Admins often meet flood limits while doing ordinary management at scale.

Adding members by hand

Adding many people to a group or channel from your contacts, quickly, is one of the fastest ways to meet a limit. Telegram treats it as a spam pattern because it is a common one. You will be told to wait, and repeated attempts may limit the account further. Invite links are the better tool: people join themselves, and there is no flood risk. See why you can't add members to a group and the invite links guide.

Joining many groups or channels quickly

Joining dozens of chats in a row, for example from a folder or a list, can trigger a temporary limit on joining. The app may refuse more joins for a while.

Changing names, usernames and links

Changing a username or a channel's public link several times in a row can lead to a wait. Telegram limits this partly to stop people squatting or cycling usernames.

Bulk deleting, forwarding and editing

Forwarding hundreds of posts, deleting large volumes of messages or editing many posts in quick succession can each meet limits. The app usually handles this by slowing down or showing a wait message.

Searching and resolving usernames

Looking up many usernames rapidly, whether in the app or through a tool, has a tight limit. Tools that check lists of usernames are a common cause of long waits.

What to do as an admin

1. Stop the action that triggered the message. Do not retry immediately.
2. Wait the time shown, plus a margin. If no time is shown, leave it for an hour.
3. Change the method: invite links instead of adding members, scheduled posts instead of many manual posts, a moderation bot instead of manual mass deletion.
4. Spread large jobs across the day.

What to do as a channel team

Teams that run large channels can avoid most limits by design rather than by luck.

• Schedule posts instead of firing them off together. Scheduled messages go out at the set time without anyone repeating actions by hand. See how to schedule messages.
• Give each admin a clear job. Each account has its own limits, so a team spreads routine work naturally. Two admins doing the same bulk task at once only doubles the activity on one chat.
• Let bots do repetitive moderation. A well-built moderation bot paces itself; a person clicking delete hundreds of times does not.
• Grow through links, not adding. Sharing invite links, folder links and cross-promotion brings people in without any account doing mass operations.

Before you start: a quick self-check for developers

Answer these before changing any code. They tell you which sections matter most.

• Does every send in your bot go through one place, or are messages sent from all over the code?
• Do you read retry_after, or do you sleep a fixed time?
• Can two copies of the bot ever run with the same token, for example during a deployment?
• Do you edit messages frequently, such as progress updates?
• Do you send to groups as well as private chats?
• Do you broadcast to all users at once?

If the answer to the first question is "all over the code", start with the send queue. Everything else is easier once sending is in one place.

Handling 429 errors in a bot: the core pattern

The basic handling is the same in any language or framework.

1. Send the request.
2. If it succeeds, carry on.
3. If it fails with 429, read retry_after from the response parameters.
4. Pause sending for that chat (or for the whole bot, if the limit is global) for at least that many seconds.
5. Retry the same request once the wait is over.
6. If it fails again with 429, repeat the wait. Do not shorten it.

Two rules make this robust:

• Never retry in a tight loop. A bot that retries instantly on 429 hammers the server and can earn longer waits.
• Pause the right scope. If one chat hit its per-chat limit, other chats can usually continue. If the bot hit its broadcast limit, everything should slow down.

Most popular bot frameworks include a helper for this. Check whether yours already has one before writing your own; built-in helpers are usually tested against real Telegram behaviour.

Designing a bot that rarely sees 429

Handling the error is the safety net. Good design keeps you away from it.

Use a send queue

Instead of sending messages directly from your business logic, put them in a queue. A single worker takes messages from the queue and sends them at a controlled pace. This gives you one place to enforce limits, retry and log.

Rate-limit at two levels

A practical setup limits sending in two ways at once:

• A global limit for the whole bot, kept comfortably under the bulk figure.
• A per-chat limit, so no single chat receives more than about one message per second, and groups stay well under the per-minute figure.

A common way to implement this is a token bucket: each chat and the bot as a whole have a bucket that refills at a steady rate, and each message spends one token. If the bucket is empty, the message waits. You do not need the name to use the idea; any limiter that spaces messages out works.

Send fewer, richer messages

Many flood problems come from sending one message per item. Combine instead.

• Put a list of results in one message rather than ten.
• Send several photos as an album using the media group method, which the Bot API supports for a small group of items in one request.
• Edit one status message rather than sending a new one for every update.

Throttle edits too

Edits count as requests. A progress bar that edits a message several times a second will hit limits fast. Update it every few seconds, or only when the percentage changes meaningfully.

Answer callback queries promptly, once

When a user presses an inline button, answer the callback query once. Answering is required for the button to stop showing a loading state, but repeated answers or extra messages for every press add load.

Cache what you can

For inline bots, the Bot API lets you tell Telegram how long it may cache results. Sensible caching cuts repeated requests for popular queries.

Receive updates efficiently

Sending is where most limits bite, but receiving can waste requests too. Bots get updates either by polling with getUpdates or through a webhook.

• If you poll, use long polling. Pass a timeout so the request waits on Telegram's side until something arrives. Polling in a fast loop with no timeout sends a stream of empty requests for no benefit.
• If you use a webhook, answer quickly. Telegram expects your server to acknowledge each update. Do heavy work after acknowledging, ideally by putting it in your queue, so slow processing does not cause Telegram to resend the same update.
• Do not mix the two. A bot with a webhook set cannot poll at the same time, and switching back and forth during deployment causes confusing errors.

Do not run two copies with one token

Two instances of the same bot, for example a forgotten test server and the live one, share the same limits but do not share a queue. Each thinks it is under the limit while together they exceed it. Make sure only one process sends for each bot token, or coordinate them through a shared queue.

Broadcasting to many users

Sending an announcement to every user of a bot is where most developers first meet 429 errors.

Plan the broadcast

1. Count recipients and work out how long the broadcast will take at a safe rate.
2. Decide whether it needs to arrive quickly. Most announcements do not.
3. Sort recipients if some should receive it first, such as active users.

Worked example: timing a broadcast

Example only, with made-up numbers. A bot has 12,000 subscribers to its announcements. The developer chooses to send at 20 messages per second, well under the documented bulk figure.

• 12,000 messages at 20 per second takes 600 seconds, which is 10 minutes.
• If the developer sent at 1 per second instead, it would take 12,000 seconds, more than three hours.

Ten minutes is fine for a newsletter. If the bot needed to reach everyone within seconds, that is the case paid broadcasts exist for, and the cost should be weighed first.

Handle failures during a broadcast

• 429: wait retry_after, then continue from where you stopped.
• The user blocked the bot (403): mark the user as inactive and do not retry. Retrying a blocked user wastes requests.
• Chat not found or deactivated user: remove or flag them.

Keep a record of who has received the message so a crash half-way does not send it twice to the first half.

Respect users

Rate limits are not the only reason to broadcast carefully. Users who receive too many messages block bots, and blocked bots lose reach. Send announcements people asked for, and consider sending them silently when they are not urgent.

Flood waits versus other errors: two different retry rules

Bots fail for many reasons, and mixing up the retry rules causes trouble.

For 429 and flood errors, follow Telegram's number. The server has told you exactly how long to wait. Waiting less fails again; waiting much more only delays your users. Use retry_after as given, perhaps with a second or two of margin.

For network errors and server errors, use exponential backoff. When a request times out or Telegram returns a temporary server error, you are not told how long to wait. The usual approach is to wait a short time, then double the wait after each failure, up to a sensible maximum such as a minute.

Add jitter to backoff. Jitter means adding a small random amount to each wait. If a hundred workers all fail at the same moment and all wait exactly two seconds, they all retry at the same moment and fail together again. Random spacing spreads them out.

Do not retry permanent errors at all. A 400 error for a malformed request, or a 403 because the user blocked the bot, will never succeed on retry. Log it and move on.

A worker that distinguishes these three cases recovers quickly from real hiccups and never wastes requests on hopeless ones.

A worker loop, step by step

Here is the logic of a sending worker described in plain steps. It translates to any language.

1. Take the next message from the queue.
2. Check the per-chat limiter for that message's chat. If the chat is cooling down, put the message back with a "not before" time and take another.
3. Check the global limiter. If the bot is at its rate, wait until a slot is free.
4. Send the request.
5. On success, mark the message done and record the time for that chat.
6. On 429, read retry_after. Set the chat's cooldown (or the global cooldown if every chat is failing) to now plus that time. Put the message back.
7. On a temporary error, put the message back with a backoff delay and increase its attempt count.
8. On a permanent error, mark the message failed with the reason and do not retry.
9. If a message has failed many times, move it to a separate "dead" list for a person to inspect, rather than retrying forever.

Steps 2 and 6 are what keep one busy chat from slowing everyone else, and step 9 is what stops a single broken message from clogging the queue.

Testing your limiter before it meets real traffic

Flood limits are hard to test against the real service, because you would have to hit them on purpose. Test your logic instead.

1. Replace the Telegram client in your tests with a fake one that returns 429 with a retry_after value on, say, every fifth request.
2. Check that the worker waits the given time and retries the same message.
3. Check that other chats keep sending while one chat is cooling down.
4. Simulate a permanent error and confirm that the message is not retried.
5. Simulate a crash mid-broadcast and confirm that a restart does not resend messages already delivered.

These five tests catch most of the bugs that cause bots to spam retries or lose messages in production.

Moderation bots during a raid

Group moderation bots face a special case. When a spam raid hits a large group, the bot may need to delete hundreds of messages and ban many accounts within minutes. That is exactly the burst pattern that triggers flood limits.

How to stay effective:

1. Prioritise. Ban or restrict the spamming accounts first; one ban stops future messages, while each deletion only removes one.
2. Use group settings to reduce the load. Temporarily enabling slow mode or restricting new members' permissions stops new spam at the source, so the bot has less to clean up.
3. Delete in batches where the API allows it. The Bot API includes a method for deleting several messages in one request, which uses far fewer requests than deleting one at a time. Check the current documentation for its limits.
4. Queue the clean-up. Let the bot work through remaining deletions at a steady pace after the raid is contained.

For the admin side of raids, read how to stop spam bots in Telegram groups.

Why splitting work across many bots is a bad idea

When one bot hits limits, a tempting fix is to create several bots and spread messages across them. For legitimate traffic this is rarely needed, and for bulk messaging it looks like an attempt to evade limits, which Telegram may treat as abuse. It also confuses users, who receive messages from bots they did not start.

Better options are to send fewer, richer messages, to spread a broadcast over a longer time, or to use paid broadcasts where speed really matters.

For developers of user-account tools

Some developers automate ordinary Telegram accounts through MTProto libraries, often called userbots. Flood limits on user accounts are stricter than on bots for many actions, because user accounts are where spam happens.

How libraries handle FLOOD_WAIT

Many MTProto libraries automatically sleep through short flood waits and only raise an error for long ones. There is usually a setting for the threshold. Know what yours does: an automatic sleep can make a script look frozen, while an error you do not catch can crash it.

Rules that keep an account safe

1. Use automation only for your own accounts and for actions Telegram's terms allow.
2. Never automate messaging people who did not ask to hear from you. That is exactly what PEER_FLOOD and account bans are for. See Telegram account banned.
3. Add generous delays between actions, especially joins, username lookups and member operations.
4. Log every flood error with the method name and the wait time. Patterns show you which action needs slowing down.
5. If waits grow longer over time, stop. The account is being treated as suspicious.

For most tasks, a bot is the safer tool. Bots have clearer limits and cannot cold-message people, which keeps them out of the spam patterns that get user accounts limited. If you have not built one before, start with how to create a bot with BotFather.

Logging and monitoring flood errors

You cannot fix what you do not see. A small amount of logging pays off.

Record, for each flood error:

• The time.
• The method or action, such as sending a message or editing.
• The chat or user it targeted.
• The wait time Telegram gave.

Then look for patterns:

• Many 429s in one chat: that chat receives too many messages; batch or slow down there.
• 429s spread across all chats at the same moment: you are hitting a global limit; lower the overall rate.
• Waits growing longer: something keeps retrying too fast; find it.
• Errors only at certain times of day: a scheduled job sends in bursts; spread it out.

Worked example: fixing a noisy group bot

Example only. A community bot posts each new item from a website feed into a group. When the website publishes many items at once, the bot gets 429 errors and some posts are lost.

1. The developer adds a queue so posts are not lost when an error happens.
2. The group limit is the problem, so the worker sends at most a few posts per minute to the group.
3. When more than three items arrive together, the bot combines them into one digest message with links.
4. On 429, the worker waits retry_after and retries from the queue.

The group now receives fewer, tidier messages, and nothing is dropped.

Common mistakes

• Retrying immediately. It extends waits and can mark the bot or account as abusive.
• Hard-coding a wait. Always read the time from the error. A fixed one-second sleep fails when Telegram asks for thirty.
• Treating PEER_FLOOD as a timer. It is a restriction caused by behaviour, not a short pause.
• Running at the published limits. Leave a margin for retries and replies.
• Ignoring edits. Fast edits are requests too.
• Two processes, one token. They share limits but not a queue.
• Mass-adding members. Use invite links instead; adding many people quickly is treated as spam.
• Buying "flood-free" tools. No legitimate tool removes Telegram's limits for spam-like activity, and many such tools put the account at risk.

FAQ

How long does a FLOOD_WAIT last?

As long as the number in the error. It can be seconds or hours. Read it, wait it, and do not retry early.

Can Telegram Premium remove flood limits?

Premium raises some limits for user accounts, such as for certain file transfers, but it does not remove anti-spam limits. Bots do not use Premium; for bulk sending they have paid broadcasts.

Why do I get 429 errors when my bot sends only a few messages?

Check for edits, callback answers, a second instance using the same token, or several messages sent to one group in a short time. The per-chat and per-group limits are much lower than the bulk figure.

Does a FLOOD_WAIT mean my account will be banned?

No. A flood wait is a temporary limit. Repeated spam-like behaviour, especially messaging strangers, is what leads to longer restrictions or bans.

Is there a list of all Telegram rate limits?

No complete official list exists. Telegram documents rough bot sending guidance in its Bots FAQ and says clients must handle flood errors. Design for unknown limits by queuing and reading the wait time.

What is the difference between 420 and 429?

420 with FLOOD_WAIT_X is the form used by Telegram's own protocol in MTProto libraries. 429 Too Many Requests with retry_after is the form the Bot API uses. Both mean wait, then retry.

Summary

FLOOD_WAIT, "too many attempts" and 429 Too Many Requests are all Telegram saying slow down. Admins should stop the action, wait, and switch to methods like invite links and scheduled posts. Bot builders should queue messages, limit per chat and globally, combine messages, throttle edits, read retry_after and never retry early. PEER_FLOOD is different: it is a restriction triggered by spam-like behaviour, and the only fix is to stop that behaviour.