Telegram Flood Wait Recovery Playbook 2026
Telegram Flood Wait Recovery Playbook 2026
what you will end up with
Follow this guide and you will have a working decision tree for the seven most common Telegram MTProto restriction errors. You will also have a Python Telethon handler that routes each error to the correct recovery action, and a clear picture of which errors are temporary versus permanent. The whole setup takes about 30 minutes if Telethon is already installed. You need a working Telegram account, Python 3.10 or later, and some patience if the account is already in a restricted state when you start reading.
before you start
You need Python 3.10 or later, Telethon 1.36 or later, and an active Telegram session file. If you are on a VPS or cloud phone, confirm the session file is not shared across multiple processes. That is one of the fastest ways to trigger AUTH_KEY_DUPLICATED. Confirm your Telethon version before going further.
pip show telethon | grep Version
# should return: Version: 1.36.x or higher
Also bookmark the Telegram MTProto error code reference now. Every error in this guide maps directly to a code in that document. When Telegram engineers update error behavior (which they do quietly, a few times per year), that page is where the changes appear first.
the step-by-step
1. Understand the two tiers of restriction.
Telegram errors split into two groups: temporary rate limits that lift on their own, and account-level actions that require a human to intervene. FLOOD_WAIT_X and SESSION_PASSWORD_NEEDED are in the first group. USER_DEACTIVATED_BAN, PHONE_NUMBER_BANNED, and FROZEN_METHOD_INVALID are in the second. Treating a permanent ban the same as a flood wait is the single most common mistake in telegram flood wait recovery setups. You end up hammering a dead account for days wondering why it never recovers.
2. Install error routing in your Telethon client.
Paste the following handler into your existing client code. It catches all seven errors covered in this guide and logs the right action for each. Read the inline comments carefully. The +5 buffer on flood waits is not optional. Telegram’s flood timer sometimes counts from server time, not your clock.
from telethon import TelegramClient
from telethon.errors import (
FloodWaitError,
PeerFloodError,
UserDeactivatedBanError,
SessionPasswordNeededError,
PhoneNumberBannedError,
AuthKeyDuplicatedError,
RPCError,
)
import asyncio
import logging
log = logging.getLogger(__name__)
async def route_rpc_error(e: RPCError):
msg = e.message
if "FROZEN_METHOD_INVALID" in msg:
log.critical(
"FROZEN_METHOD_INVALID: account is frozen by Telegram. "
"All API calls will fail. File appeal at recover.telegram.org "
"and do not retry until the freeze is lifted."
)
elif "AUTH_KEY_DUPLICATED" in msg:
log.critical(
"AUTH_KEY_DUPLICATED: your .session file is being used from "
"two different IPs simultaneously. Kill all processes, delete "
"the .session file, and re-authenticate from one IP only."
)
else:
log.error("Unhandled RPC error: %s (code %s)", msg, e.code)
async def safe_send(client: TelegramClient, peer, message: str):
try:
await client.send_message(peer, message)
except FloodWaitError as e:
# Temporary. Wait exactly as long as Telegram says, plus a buffer.
wait = e.seconds + 5
log.warning("FLOOD_WAIT_%d: sleeping %ds before retry", e.seconds, wait)
await asyncio.sleep(wait)
except PeerFloodError:
# Semi-permanent. Your account is flagged for mass messaging.
# Stop ALL outbound messages for 24-48h minimum.
log.error(
"PEER_FLOOD: mass-message flag active. "
"Halt all sends. Do not switch IPs yet. Wait 24h then test with one message."
)
except UserDeactivatedBanError:
# Permanent ban. Account cannot be recovered through the API.
log.critical(
"USER_DEACTIVATED_BAN: account is permanently banned. "
"Appeal at recover.telegram.org. Success rate is low for accounts "
"flagged for spam. Retire the number if no reply within 7 days."
)
except SessionPasswordNeededError:
# 2FA challenge, not a ban. Re-authenticate with the cloud password.
log.error(
"SESSION_PASSWORD_NEEDED: Telegram is demanding 2FA verification. "
"Call client.start(password='your_2fa_password') to resume the session."
)
except PhoneNumberBannedError:
# The number itself is banned, not just the session.
log.critical(
"PHONE_NUMBER_BANNED: the phone number is banned at the carrier/number level. "
"A new session on the same number will also fail. Appeal or retire."
)
except AuthKeyDuplicatedError:
# Named exception for the same case route_rpc_error handles via string match.
log.critical(
"AUTH_KEY_DUPLICATED: session conflict. Delete .session file. "
"Re-login from a single IP. Never run two clients with the same session."
)
except RPCError as e:
await route_rpc_error(e)
raise
3. Handle FLOOD_WAIT_X correctly.
FLOOD_WAIT_X is the most common error you will see during any automated Telegram work. Telegram returns it when you exceed the per-method rate limit. The X is seconds. The MTProto error reference classifies these as 420-class errors. Some waits are 30 seconds. After an aggressive sending session, you can see waits of 86,400 seconds (24 hours). Respect every number the server gives you. Requests sent during the wait window reset the timer on some method types. This is a pure backoff situation: sleep, do not retry, do not switch accounts mid-wait.
4. Diagnose PEER_FLOOD before touching anything.
PEER_FLOOD is different from FLOOD_WAIT. No timer. It means Telegram’s spam classifier has flagged your account for sending too many messages to users who are not in your contacts. This is the error people see right before a more serious action. Stop all outbound messages completely, wait at least 24 hours, and test with a single message to a known contact. Do not switch IPs at this stage. Switching IPs mid-PEER_FLOOD is what converts a recoverable flag into a harder ban. Read more about why Telegram reaches this decision in why Telegram bans accounts.
5. Handle AUTH_KEY_DUPLICATED immediately.
This one is your own fault and you can fix it fast. It happens when the same .session file is used from two different IP addresses at the same time, or when a session created on one IP gets moved to another without re-authentication. Telegram’s MTProto layer issues auth keys tied to a specific key exchange, and when it sees the same key from two IPs, it kills both. Stop every process using the session file, delete it, and sign in again from one fixed IP. If you regularly copy session files between machines, this error will keep coming back. One session, one IP, always.
6. Respond to SESSION_PASSWORD_NEEDED without panicking.
This is not a ban. Telegram is asking for your 2FA cloud password before it will continue. It shows up when you sign in from a new device or IP without providing the password during the initial start() call. Call client.start(password='your_cloud_password') and the session resumes. If you do not know the 2FA password, that is a recovery problem, not an API problem. See how to set up Telegram 2FA without losing account for the guide on that.
7. Treat FROZEN_METHOD_INVALID and number-level bans as escalations.
FROZEN_METHOD_INVALID appears when Telegram has frozen an account due to suspicious activity, often right before a permanent action. It is not listed cleanly in every version of the Telethon named exception list, so catch it via the string match shown in step 2. No API method will succeed while this error is active. File an appeal at recover.telegram.org and wait. PHONE_NUMBER_BANNED and USER_DEACTIVATED_BAN are the terminal states. Both require an appeal at the same URL. Expect 3 to 7 days for a response, and expect a low success rate if the account was flagged for spam. The EFF’s account recovery guidance applies here too: document everything before the ban, because you will not have access to evidence once the account is gone.
8. Build a test harness for each error path.
Before running this handler in production, test it. Telethon lets you raise named exceptions directly in tests. For FloodWaitError, you can construct one with FloodWaitError(request=None, capture=30) and pass it through your handler to confirm the sleep logic runs. For string-matched errors like FROZEN_METHOD_INVALID, write a mock RPCError with the right message attribute. Untested error handlers give false confidence. The telegram flood wait recovery path that only fires when something is already wrong is exactly the path most developers skip testing.
what can go wrong
You sleep for the right duration but the flood wait resets. This happens when your code sleeps the correct number of seconds but immediately retries with the same request. Some methods have a separate limit on retry frequency. After sleeping, wait one more minute before resuming normal operation, not just the one banned request.
PEER_FLOOD persists after 48 hours. If the error is still active after two days of silence, the flag may have escalated to a soft restriction requiring appeal. File at recover.telegram.org with the phone number in international format and a brief description of what the account was doing. Do not mention automation tools in your appeal.
AUTH_KEY_DUPLICATED recurs after you re-login. If you deleted the session and re-logged in but the error comes back within hours, something else is using the session file. Check cron jobs, supervisor processes, and any Docker containers that might have a copy of the old session mounted as a volume. The problem is almost always a second process, not a Telegram-side issue.
USER_DEACTIVATED_BAN fires on a newly registered number. This happens when a number was previously banned by a prior owner and then recycled by the carrier. The ban is on the number, not the person. The only path is appeal. If appeal fails, retire the number and start fresh. This is why number sourcing matters. See dedicated vs shared mobile IPs for more on how number history affects Telegram account health.
how this looks on managed hosting
On a telegramvault cloud phone, the session lives on a physical Android device in Singapore pinned to a single SingTel, M1, StarHub, or Vivifi SIM. AUTH_KEY_DUPLICATED is structurally impossible because the session never moves between IPs. The IP is static and mobile-carrier-grade, so the chance of triggering PEER_FLOOD from an IP already flagged by Telegram’s network-level classifier is far lower than it would be on a datacenter or residential proxy pool. When a FLOOD_WAIT_X fires, it is always tied to the account’s own behavior, not shared IP reputation. You handle the wait, the hardware stays up. For SESSION_PASSWORD_NEEDED, the customer is the only one who knows their 2FA password, so they handle re-authentication themselves via the browser STF session. We never see the OTP or the cloud password. That separation is the whole point of the BYO number Telegram hosting model.
recovery if you mess up
If you have already hit a serious error and want to know where you stand, check this in order. First, try signing in manually in the Telegram app on any phone. If you can sign in normally, the restriction is session-level or method-level, not a full ban. Second, if the app shows “your account has been suspended,” go to recover.telegram.org immediately. Do not wait. Submit the appeal with the phone number in international format, a brief description of the account’s legitimate use, and nothing else. Telegram support response times in 2026 range from 3 days to 3 weeks depending on queue volume. OONI’s network interference reports are useful for understanding whether Telegram itself is having regional issues, which can sometimes mimic account restrictions. Third, if you cannot sign in and the appeal goes unanswered for 10 days, the account is likely permanently gone. Retire the number, export any data you still have access to from other devices, and start clean.
related tasks
Understanding telegram flood wait recovery gets easier once you know why Telegram issues these signals in the first place. The spam classifier that triggers PEER_FLOOD and escalates to USER_DEACTIVATED_BAN is built on account behavior patterns, IP reputation, and message content signals. The full breakdown is in why Telegram bans accounts.
If you are running multiple accounts and hitting flood waits across several simultaneously, the issue is often the IP rather than the accounts themselves. A shared residential proxy pool that routes dozens of accounts through the same egress IP generates compound restrictions. The distinction between dedicated and shared IPs at the carrier level is covered in dedicated vs shared mobile IPs.
For accounts that need to recover from a flagged state without losing group memberships and channel history, rotating out of a bad IP situation without triggering a new error is its own topic. The post on how to rotate out of a flagged IP without losing the account walks through that sequence step by step.
Session hygiene is the underlying issue in most AUTH_KEY_DUPLICATED cases. If you are managing more than five accounts, keeping sessions isolated by device and IP becomes real operational overhead. That is the problem the telegramvault infrastructure is built to solve at scale.
final word
Most telegram flood wait recovery failures are not mysterious. They are predictable consequences of a small set of bad habits: sharing sessions across IPs, ignoring wait timers, and misreading permanent bans as temporary ones. The decision tree in this guide covers all the errors that matter in 2026 and gives you the right action for each one. If you want the infrastructure layer handled for you, the telegramvault waitlist is open now.