Common Telegram Bot Errors and How to Fix Them
· 4 min read · 18+ readers

Most Bot API problems come from a short list of causes. This page lists the errors you will see most often, what they usually mean and how to fix them. Messages are quoted as Telegram has used them, and wording can change slightly, so search for the key phrase. When a response has
"ok": false, read error_code and description first.
Quick table
| Code and message | Usual cause | Fix |
|---|---|---|
| 401 Unauthorized | Wrong or revoked token | Copy the token again, check for spaces, use /token in BotFather |
| 404 Not Found | Wrong method name or malformed URL | Check spelling and the bot<TOKEN> part |
| 400 Bad Request: chat not found | Wrong chat id, or the user never started the bot | Use the id from an update, ask the user to press Start |
| 400 Bad Request: can't parse entities | Unescaped HTML or MarkdownV2 | Escape user text or send without parse_mode |
| 400 Bad Request: message is too long | Text over 4096 characters | Split the message |
| 400 Bad Request: message is not modified | Edit with identical text and markup | Skip the edit |
| 400 Bad Request: query is too old | Callback or inline query answered late | Answer within seconds, always call answerCallbackQuery |
| 403 Forbidden: bot was blocked by the user | The user blocked the bot | Mark them inactive, stop sending |
| 403 Forbidden: bot is not a member of the channel chat | Bot not added or removed | Add it as admin |
| 403 Forbidden: bot can't initiate conversation with a user | User never started the bot | Wait for them to message first |
| 409 Conflict: terminated by other getUpdates request | Two pollers, or a webhook is set | Run one instance, call deleteWebhook |
| 409 Conflict: can't use getUpdates method while webhook is active | Webhook is set | deleteWebhook first |
| 429 Too Many Requests: retry after N | Sending too fast | Wait N seconds, add a queue |
| 502, 503, 504 | Retry with backoff |
Authentication and setup
401 after it worked yesterday: someone revoked the token, or you rotated it and forgot to deploy. Check getMe with the token in use. See token safety.
Bot does not respond at all: check that the process runs, that you call the right update method, and that no webhook blocks polling. Use getWebhookInfo.
Polling problems
409 Conflict: a second copy is polling, perhaps on another machine or an old container. Stop others. If you switched to a webhook, call deleteWebhook. See webhook vs long polling.
Updates repeat after restart: you did not advance offset. Set it to the highest update_id plus one before the next call.
Missing update types: allowed_updates excludes them. Some types, such as chat_member, need to be listed.
Webhook problems
Call getWebhookInfo and read last_error_message:
- SSL error or wrong certificate: use a valid, complete certificate chain and a matching domain.
- Wrong response code from the webhook: your server returned a non 2xx status. Fix the route.
- Connection timed out: the server is too slow or blocked by a firewall. Respond fast and queue work.
- Pending updates growing: your handler fails or is too slow.
Also check that you use an allowed port and that the secret header check does not reject Telegram because of a wrong value.
Sending problems
Parse errors: with HTML, escape <, > and & in user text. With MarkdownV2, many characters need a backslash. If you cannot escape reliably, omit parse_mode.
Photo or file errors: wrong URL, file too large, or unsupported type. Check size limits in the reference.
Cannot message a user: they did not start the bot or blocked it. This is permanent until they act.
Groups and channels
- Bot ignores messages: privacy mode. See privacy mode and admin rights.
- not enough rights: give the bot the specific permission.
- Group upgraded to supergroup: the chat id changes. The error response may include
migrate_to_chat_id. Update your stored id. - Topics: include
message_thread_idto reply in the right topic.
Payments
- Invoice not shown: check currency
XTR, a single price item, and a title and description within limits. - Payment hangs: you did not answer
pre_checkout_querywithin about 10 seconds. - Double delivery: a repeated update. Use idempotency. See Stars payments.
Mini Apps
- Blank screen: HTTPS error, mixed content or a script that failed. Open the console in Telegram Desktop, which supports web inspector options in debug mode, or test in a browser.
initDataempty: the page was opened outside Telegram.- Validation fails: wrong secret formula. See initData validation.
A debugging routine
- Reproduce with a second account. See testing.
- Log the full error object, without secrets.
- Check
getMeandgetWebhookInfo. - Reduce the request to the smallest failing call.
- Compare with an example in the documentation.
- Update your library and read its changelog.
Frequently asked questions
Where is the official list of errors?
Telegram does not publish a complete list. Use description strings and the Bot API FAQ.
Why does the same call work for me but not for users?
You are the owner, with different rights and history. Test with a second account.
Should I retry every error?
No. Retry network errors, 429 and 5xx with backoff. Do not retry 400 and 403 without a change.
What if Telegram itself is down?
Retry with backoff and check Telegram's official status channels.
Related guides

Telegram Bot API Basics: Methods, Updates and Responses
How the Telegram Bot API works: URL format, JSON responses, update objects, common methods, parse modes, keyboards and how to read errors.

Webhook vs Long Polling for Telegram Bots
Compare getUpdates long polling and setWebhook for Telegram bots: how each works, trade-offs, limits, when to switch and how to migrate safely.

Telegram Bot Rate Limits and Flood Control
Understand Telegram's bot limits: messages per second and per chat, 429 errors and retry_after, broadcasting safely, queues and backoff, with a Node example.

Bot Privacy Mode and Group Admin Rights Explained
What a bot can see in groups: privacy mode on and off, admin rights, allowed_updates, mentions and commands, and how to test and change them safely.

Test Your Telegram Bot with a Second Account
A practical testing routine for Telegram bots: second accounts, a dev bot, test groups, payment tests, Telegram's test environment and a pre-launch checklist.

A Telegram Webhook on AWS Lambda or a Small Server
Two ways to receive Telegram updates: an AWS Lambda function URL and a tiny Node server behind HTTPS, with secret token checks, fast replies and queues.
More in Build on Telegram
- Add a Bot as Channel Admin and Post to Your Channel
- BotFather Commands: What Each One Does
- Connect a Bot to Your Telegram Business Account (Chatbot Mode)
- Connect Your Backend to a Telegram Bot: A Practical Architecture
All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial