Telegram FLOOD_WAIT Error: Causes, Timers, and Ban Risk 2026

the short definition

The telegram FLOOD_WAIT error is a rate-limiting signal from Telegram’s MTProto servers. It fires when a client exceeds the allowed call frequency for a specific API method. The error code is 420-class, always formatted as FLOOD_WAIT_X, where X is the number of seconds the client must pause before retrying. The wait duration scales with how aggressively the limit was crossed, and Telegram enforces it per method and per account.

the longer explanation

Telegram’s MTProto protocol has had rate-limit enforcement baked in since the early API days, formalized under what the platform calls flood protection. The telegram.org/mtproto/error_codes" target="_blank" rel="noopener">official MTProto error code reference documents 420-class errors as flood errors: the caller must wait before making another request. The number appended to FLOOD_WAIT is not arbitrary. Telegram’s servers compute it in real time based on how many excess requests were made and how quickly. A modest overrun might return FLOOD_WAIT_30. A sustained burst can return FLOOD_WAIT_86400, which is 24 hours exactly. Both timers are enforceable. Neither is negotiable.

The limits are not uniform across methods. Some are far more sensitive than others. messages.sendMessage has one threshold. contacts.importContacts has a much stricter one. channels.joinChannel is among the most tightly controlled because mass group-joining is a primary spam vector. The exact per-method numbers are not fully published, but they are well-established through years of community testing. The practical consensus across Telethon, Pyrogram, and GramJS maintainers is that sending more than 20 to 30 messages per minute to non-contacts is the fastest way to trigger a flood wait on a standard user account.

The error works differently for bot accounts. Bots authenticated through BotFather and using the telegram.org/bots/api" target="_blank" rel="noopener">Telegram Bot API are subject to different rate ceilings: 30 messages per second global throughput, 20 messages per minute to any single group or channel. When a bot hits them, it receives a 429 Too Many Requests HTTP response containing a retry_after value in seconds. Functionally equivalent to FLOOD_WAIT_X, but delivered through the HTTP interface instead of the binary protocol. Critically, bot flood errors do not threaten the underlying account. The token is rate-limited, you wait, you retry, and nothing accumulates.

User accounts are a different story. MTProto user sessions carry identity weight: a phone number, an account age, a history of group memberships, a reputation built over months or years. When a user account triggers repeated FLOOD_WAIT errors through sustained API abuse, the errors themselves are not the immediate danger. What builds underneath them is. Telegram’s spam detection systems observe the call patterns generating the flood waits and use them as behavioral signals. That is the mechanism by which a series of FLOOD_WAIT events, handled incorrectly, can precede escalation to PEER_FLOOD and eventually to account restriction. The telegram FLOOD_WAIT error is not a punishment. It is a warning that Telegram is watching what the account is doing.

why it matters for telegram operators

If you are running a Telegram account for real business work, managing a community, or operating a channel with an audience that took months to build, every FLOOD_WAIT you generate is logged against the account’s behavioral profile. Three FLOOD_WAIT errors in a session is noise. Three hundred is a signal the account is sending automated traffic. Telegram’s anti-spam systems are not naive about this. The platform had over 950 million monthly active users as of early 2024, according to Reuters, and a meaningful fraction run some form of automation. Telegram has had years to calibrate what normal human behavior looks like versus scripted traffic.

The escalation chain moves in one direction. A FLOOD_WAIT_X is temporary and account-neutral if you respect it. PEER_FLOOD, the next escalation step, is not. PEER_FLOOD fires when Telegram’s classifier decides the account is actively abusing peer messaging, typically after repeated violations of contacts-message limits or after mass-adding users from scraped lists. At that point the account cannot send messages to non-contacts at all, and no wait timer clears it. Recovery requires a multi-day pause in all outbound activity, not just a sleep and retry. From PEER_FLOOD, the path leads to account suspension: USER_DEACTIVATED_BAN, which is permanent, or a freeze that can sometimes be lifted through the recover.telegram.org appeal process. The full breakdown of how Telegram reaches those decisions is in why Telegram bans accounts.

Operators running accounts from datacenter infrastructure or shared proxy pools are more exposed than they realize. The reason is not just behavior; it is IP context. When Telegram’s servers evaluate how seriously to respond to rate-limit violations, they weight the signal from accounts running on known datacenter ASNs more heavily than accounts on consumer mobile ASNs. An account connecting from a Hetzner or DigitalOcean IP range, triggering FLOOD_WAIT on message sends, then switching IPs to mask the pattern, generates a compound signal that looks nothing like a human user. The telegram FLOOD_WAIT error is the visible part. What Telegram is watching is the whole behavioral fingerprint underneath it.

common misconceptions

Switching IPs clears an active FLOOD_WAIT. It does not. The timer is tied to the account, not the IP address or session. Moving a session to a different server, proxy, or SIM while a FLOOD_WAIT is active does not reset the timer. The counter lives server-side on Telegram’s infrastructure, keyed to the account’s authorization. When the timer expires, it expires. When it has not, it has not, regardless of where you connect from. Switching IPs mid-wait adds another behavioral signal (a session migration event) to an account already under scrutiny. That is the kind of compounding action that converts a recoverable flood wait into something harder to undo.

FLOOD_WAIT and PEER_FLOOD are the same error at different severity levels. They are distinct errors with different causes and different recovery paths. FLOOD_WAIT_X is a method-rate-limit response. The X tells you exactly how long to wait, and once that time passes, you can retry. PEER_FLOOD has no timer. It fires when Telegram’s classifier flags the account for mass messaging to non-contacts, typically from sustained behavioral patterns rather than any single method call. Recovery from PEER_FLOOD is not waiting a number of seconds. It is stopping all outbound messaging for 24 to 48 hours and resuming conservatively. Operators who treat PEER_FLOOD like a longer FLOOD_WAIT are the ones who end up with permanent bans.

Bot accounts can be banned for FLOOD_WAIT violations the same way user accounts can. Bot tokens and user accounts operate under different rules. A bot receiving 429 Too Many Requests is having its token rate-limited, not its underlying account threatened. When Telegram throttles a bot, the token resumes after the retry_after window. The bot does not accumulate a behavioral score the same way a user account does. If a bot gets banned, it is because it violated content policies or was reported, not because it sent too many messages too fast. The rate-limit system for bots is a traffic shaper. For user accounts, the relationship is different, and that distinction changes how seriously you have to take each event.

The wait duration is an estimate you can safely shorten. The wait duration is exact, but Telegram’s clock and your client’s clock are not guaranteed to be synchronized to the millisecond. Library maintainers for Telethon and Pyrogram recommend adding 5 seconds to whatever FLOOD_WAIT_X reports. If your client’s clock is slightly behind the server’s, you retry at what looks like the right time but the server’s timer has not yet expired. The retry counts as another request during the restricted window, which can reset the flood timer on some method types. The extra 5-second buffer costs almost nothing and avoids a common edge case where a correctly-written retry loop still fails because of clock skew.

a quick worked example

Here is how to correctly catch the telegram FLOOD_WAIT error in Telethon, read the exact wait duration from the exception, and handle the escalation to PEER_FLOOD cleanly. Run the IP check at the bottom before deploying anything; the ASN field tells you immediately whether your session IP looks like a phone or a server.

import asyncio
import logging
from telethon import TelegramClient
from telethon.errors import FloodWaitError, PeerFloodError

log = logging.getLogger(__name__)

API_ID   = 12345678        # from my.telegram.org
API_HASH = "your_api_hash"
SESSION  = "my_session"

async def send_with_flood_handling(client, peer, text):
    try:
        await client.send_message(peer, text)
        log.info("sent to %s", peer)

    except FloodWaitError as e:
        # e.seconds is the integer the server returned in FLOOD_WAIT_X.
        # add 5s buffer for clock skew; do not subtract from it.
        buffer = 5
        wait_total = e.seconds + buffer
        log.warning(
            "FLOOD_WAIT_%d received. sleeping %ds (server + %ds buffer)",
            e.seconds, wait_total, buffer,
        )
        await asyncio.sleep(wait_total)
        await client.send_message(peer, text)  # one retry only

    except PeerFloodError:
        # no timer, no wait value. this is not a FLOOD_WAIT escalation.
        # halt ALL outbound sends. do not switch IPs. wait 24h minimum.
        log.error(
            "PEER_FLOOD active. stop all sends now. "
            "switching IPs here makes this worse, not better."
        )
        raise

async def main():
    async with TelegramClient(SESSION, API_ID, API_HASH) as client:
        # before sending anything, check the session IP's ASN.
        # run this in a shell: curl -s https://ipinfo.io/json | python3 -m json.tool
        # "org" field should show a mobile carrier (e.g. "AS9506 Singtel"),
        # not "Hetzner", "DigitalOcean", "OVH", or any datacenter name.
        peers = ["@channel_a", "@channel_b", "@channel_c"]
        for peer in peers:
            await send_with_flood_handling(client, peer, "hello")
            await asyncio.sleep(4)  # 3-5s gap between sends cuts flood risk substantially

asyncio.run(main())

The e.seconds attribute on FloodWaitError is the raw integer from FLOOD_WAIT_X. No parsing required. Telethon, Pyrogram, and GramJS all expose this value directly on the exception object. If you are using a library that does not, you are reading the raw error string and extracting the integer after the underscore yourself. The MTProto error code specification confirms the format: FLOOD_WAIT_%d where %d is seconds, always an integer, always positive.

how telegramvault relates

Every session on a telegramvault cloud phone connects to Telegram from a static IP belonging to a real Singapore carrier SIM, either SingTel, M1, StarHub, or Vivifi. The IP never rotates and has never been shared with another customer. When a FLOOD_WAIT fires on a telegramvault account, it is tied to the account’s own behavior, not to shared IP history or a prior customer’s abuse patterns inherited through a proxy pool. Accounts on datacenter IPs or shared residential proxy pools can receive elevated scrutiny from Telegram’s systems before the first message is even sent, purely because of the IP’s prior reputation. On a dedicated Singapore mobile IP, the floor is cleaner. If you trigger a FLOOD_WAIT, it is because your code sent too many requests too fast. The fix is what it should be: respect the timer, reduce the call rate, and the account stays intact. The relationship between IP type and account survival is covered in detail in dedicated vs shared mobile IPs.

further reading

Understanding the telegram FLOOD_WAIT error in isolation is only part of the picture. The broader question is what causes Telegram to take action beyond a rate-limit warning, and that requires understanding how the spam classifier actually works. The post on why Telegram bans accounts maps the full decision tree: which behavioral signals accumulate, how IP reputation feeds into the classifier, and what separates a recoverable flood wait from a permanent account action.

If you are hitting FLOOD_WAIT errors across multiple accounts running simultaneously, the IP layer is worth investigating before adjusting anything in your code. When multiple accounts share an IP, their combined call volume against Telegram’s servers is attributed to that IP. A mobile proxy pool routing dozens of sessions through a small number of egress IPs generates compound rate-limit pressure that individual accounts cannot explain on their own. The dedicated vs shared mobile IPs post covers exactly this dynamic and explains why shared IP history is invisible to you but visible to Telegram.

For operators running bots alongside user accounts, the rate-limit model differs substantially between the two. The post on Telegram Bot API vs User API vs MTProto limits breaks down both systems in detail and explains when working within the 30-messages-per-second Bot API ceiling is the right call, versus when a user account’s more nuanced and riskier limit structure is unavoidable.

The FLOOD_WAIT error sits within a larger family of MTProto restriction errors, each with different recovery procedures. The full recovery playbook covering PEER_FLOOD, AUTH_KEY_DUPLICATED, FROZEN_METHOD_INVALID, and USER_DEACTIVATED_BAN alongside FLOOD_WAIT is in the Telegram Flood Wait Recovery Playbook on this site. If you have already triggered something and are not sure which error you are dealing with, that is the right place to start.

final word

The telegram FLOOD_WAIT error is one of the few genuinely informative signals Telegram sends before something worse happens. It tells you the call rate exceeded what the method allows, and it gives you the exact number of seconds to wait before trying again. Ignore it, or treat it as something to route around rather than respect, and the account’s behavioral profile accumulates the kind of pattern Telegram’s classifier eventually acts on permanently. If you want infrastructure where FLOOD_WAIT events reflect only your own call behavior and not inherited IP reputation, the telegramvault waitlist is open now.