The short answer
- 1Each error has a number (category) and a name (reason); handle by name, fall back to number.
- 2FLOOD_WAIT_X: wait exactly X seconds before retrying.
- 3303 means switch data center; 401 means log in again.
In this article
An error has a number and a name
Telegram API errors come in two parts: a numeric code, which is the broad category, and an error name in capitals and underscores, which is the specific reason, for example PHONE_CODE_INVALID. Decide what to do from the name, and fall back to the number when you meet a name you do not know. Where a name ends in _X, that part is a number: seconds, a data center number and so on.
| Code | Meaning | Typical names and what to do |
|---|---|---|
| 303 | Go to another data center | PHONE_MIGRATE_X, USER_MIGRATE_X, FILE_MIGRATE_X, NETWORK_MIGRATE_X: move to data center X and repeat the request; see data centers and _MIGRATE errors |
| 400 | The request is wrong | The input needs fixing; tell the user in plain words |
| 401 | Login required | AUTH_KEY_UNREGISTERED, SESSION_REVOKED, SESSION_EXPIRED: the session ended, log in again; see the login flow |
| 403 | Not allowed | The other person's privacy settings or missing admin rights; sending again gives the same result |
| 404 | It does not exist | A deleted message or chat, for example |
| 406 | Something to tell the user separately | Your app does not show this error itself; the server shows the user a service notice |
| 420 | Too many requests, too fast | FLOOD_WAIT_X: wait X seconds, then try again |
| 500 | A problem on the server | Try again a little later; if it keeps happening, try a smaller request |
Treat any number not in the table as a server-side problem (500). The official documentation lists possible errors for each method, but do not assume that list is complete; be ready for names you have never seen.
FLOOD_WAIT: waiting is the right answer
FLOOD_WAIT_X means "do not make this request for X seconds". Wait exactly that long, then send it again. Repeating the request while you are supposed to wait makes the wait longer, and doing it repeatedly can get the account restricted.
FLOOD_PREMIUM_WAIT_X is a speed limit that applies only to accounts without Premium, such as download speed for files; it does not apply to Telegram Premium accounts.
The real fix is fewer requests. Cache information instead of asking for it again and again (see pagination with offset and hash), and space out anything that sends to many chats.
The order of handling, in one line each
- If you know the name, act on the name: move, log in again, wait, or fix the input.
- If you do not know the name, act on the number.
- If you do not know the number either, treat it as a server problem and retry once, a little later.
Errors from the HTTP Bot API look slightly different (ok:false, error_code, description); see your first Bot API requests.
FAQ
What does FLOOD_WAIT mean in the Telegram API?
You made too many requests. FLOOD_WAIT_X tells you to wait X seconds before sending that request again.
What should I do with a 303 error?
Move to the data center number in the error name, such as USER_MIGRATE_X, and repeat the request there.
What do 401 errors like SESSION_REVOKED mean?
The session was ended, for example from the Devices list. Send the user back to log in.
Sources
At a glance
- 1Name first
The error name says what to do; the code is the fallback.
- 2FLOOD_WAIT
Wait X seconds; retrying early makes it worse.
- 3Unknown
Treat as a server problem and retry once, later.
Updated
