Sign in with TelegramTelegram Bot API Error Decoder
Telegram said no. Here is what it meant.
A whole JSON response, a library exception, an error name, or just the number. Nothing you paste is sent anywhere.
Debugging a bot that sells access to a channel? See how MemberPilot handles paid access.
How to read a Telegram error
Every failed Bot API call returns the same shape: ok: false, a numeric error_code, and a description. The number tells you the category. The description tells you the bug. Logging only the number is why so many Telegram problems get filed as “400 error” and stay open.
Some responses add a parameters object, and when they do it usually contains the fix: retry_after for rate limits, migrate_to_chat_id when a group has become a supergroup and its ID has changed underneath you.
Log the description
What this dataset is
22 errors, each written from Telegram’s documentation and from behaviour we have hit running a Telegram membership product. Where an error genuinely has several causes, all of them are listed rather than the most common one presented as the answer.
It is not exhaustive, and it does not pretend to be. Telegram does not publish a complete enumeration of Bot API error strings, so anything not covered here is best searched as the exact quoted description.
The three that account for most reports
Formatting failures. MarkdownV2 reserves eighteen characters and rejects the whole message if one is unescaped. Escape the text rather than hunting the character.
Keyboard failures. callback_data is limited to 64 bytes. The keyboard builder counts them for you.
Wrong chat ID. Supergroup and channel IDs start with -100, and a group that upgrades gets a new one. Read the ID from a real update instead of storing what someone typed.
Common questions
What does 400 Bad Request mean in the Telegram Bot API?
It means Telegram understood the request and refused it. The useful part is never the number: it is the description string beside it, which names the specific objection — chat not found, can't parse entities, message is too long, BUTTON_DATA_INVALID. Two 400s with different descriptions are two unrelated bugs.
How do I handle 429 Too Many Requests?
Read parameters.retry_after from the response and wait exactly that many seconds before repeating the request. Do not pick your own delay and do not retry in a loop, which extends the wait. For broadcasts, queue the sends: Telegram's guidance is roughly 30 messages per second overall and about one per second to the same chat.
Why does my bot get 401 Unauthorized?
The token is wrong or revoked. Telegram rejects the request before looking at what it asked for, so nothing else in your code is implicated. Test the token against getMe on its own, then check every environment that stores a copy of it.
What causes 409 Conflict?
Two consumers are competing for the same bot's updates: two running copies of the bot, or long polling while a webhook is still set. Telegram delivers each update to exactly one place. Run one consumer per token, and use a separate token for local development.
Where do the uppercase error names come from?
Names like BUTTON_DATA_INVALID and PEER_ID_INVALID come from Telegram's underlying MTProto layer and sometimes surface in the Bot API's description field. They are matched here alongside the plain-English descriptions because both spellings turn up in real logs.
Sources
Everything this tool asserts about Telegram comes from Telegram’s own documentation.