Over ten thousand files handle FLOOD_WAIT. Stack Overflow has one question about it

I searched GitHub on 17 September 2026 for code that references FloodWaitError. More than ten thousand files came back. Then I searched Stack Overflow for the same thing and got a single question.

That gap is the whole story. Everybody who automates Telegram eventually meets this error, and nearly nobody writes down what they learned. The knowledge is scattered across 222 issue threads, 32 of them still open, and most of those end with «nevermind, I added a sleep».

So here is the write-up I wanted when I first hit it.

What the error actually is

FLOOD_WAIT_X is the server telling you two things at once: this request was rejected, and do not send another one of this kind for X seconds. The number is not a suggestion and it is not constant. It depends on the method you called, on how often you have been calling it, and on the history of the account making the call.

The clients already know about it. Telethon carries a flood_sleep_threshold: below it, the client sleeps and retries for you, above it, the error reaches your code. That default is the reason so many people believe they never hit rate limits until one day they hit a big one.

Why retrying immediately makes things worse

The reflex is to catch the error and retry. Sometimes with a while True around it. That is the single most common shape in those 222 issues, and it is the one that turns a pause into a problem.

Two things happen when you retry before the timer runs out.

First, the rejected request still counts as a request. You are asking a system that already told you to slow down to do more work, and the answer is a longer timer.

Second, and this is the part people learn late, the limit is attached to the account, not to the script. A ten-second pause in a loop looks harmless in your terminal. From the other side, it is a client that ignores instructions. That is the behaviour that escalates from a wait into a limited account, and Telegram does not publish the rules for when it does.

I am not going to pretend I know the exact thresholds. Nobody outside Telegram does. What is observable is the direction: waiting works, ignoring the wait does not.

What to do instead

Respect the number you were given. Sleep for X, then continue. If X is larger than your job can tolerate, the job is too aggressive, not the timer.

Back off on top of the timer. Add a margin. A retry that lands one second after the window opens behaves like an eager client again.

Cut the number of calls before you tune the sleeps. Most scripts that drown in FLOOD_WAIT are polling for changes that could be cached, or re-fetching history they already have on disk. Rate limits are a symptom of the request pattern, not of the library.

Do not multiply sessions. Spreading the same load across three accounts to avoid the timer is the fastest known route to losing all three. This is the advice people give each other in those issue threads, and it is bad advice.

Separate «my account acts» from «I read public data». This is the distinction worth thinking about before you write any retry logic at all.

The question under the timer

Half the projects that fight FLOOD_WAIT are not automating a Telegram account in any meaningful sense. They are reading public channels: posts, view counts, the discussion under a post. They signed up for a phone number, a session file, and a rate limiter, because that is what every tutorial hands you.

If your program genuinely acts as a user, joining, sending, reacting, then you need a session and you need this discipline. Pin a maintained client, respect the timer, keep one account. Which client is actually maintained is a separate question, and the answer moved this year.

If it only reads what anyone can read without logging in, the session is a cost you took on by accident. That is the case we built tgAtlas for: public channels over HTTP, no phone number, no session file, limits that come from a plan instead of from a mood. The free plan allows 2,500 requests and 2,500 lookups a month, which is enough to find out whether your project needed an account in the first place.