TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Common Telegram Bot Errors and How to Fix Them

· 4 min read · 18+ readers

Common Telegram Bot Errors and How to Fix Them: TSocial guide cover card

Most Bot code icon 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 messageUsual causeFix
401 UnauthorizedWrong or revoked tokenCopy the token again, check for spaces, use /token in BotFather
404 Not FoundWrong method name or malformed URLCheck spelling and the bot<TOKEN> part
400 Bad Request: chat not foundWrong chat id, or the user never started the botUse the id from an update, ask the user to press Start
400 Bad Request: can't parse entitiesUnescaped HTML or MarkdownV2Escape user text or send without parse_mode
400 Bad Request: message is too longText over 4096 charactersSplit the message
400 Bad Request: message is not modifiedEdit with identical text and markupSkip the edit
400 Bad Request: query is too oldCallback or inline query answered lateAnswer within seconds, always call answerCallbackQuery
403 Forbidden: bot was blocked by the userThe user blocked the botMark them inactive, stop sending
403 Forbidden: bot is not a member of the channel chatBot not added or removedAdd it as admin
403 Forbidden: bot can't initiate conversation with a userUser never started the botWait for them to message first
409 Conflict: terminated by other getUpdates requestTwo pollers, or a webhook is setRun one instance, call deleteWebhook
409 Conflict: can't use getUpdates method while webhook is activeWebhook is setdeleteWebhook first
429 Too Many Requests: retry after NSending too fastWait N seconds, add a queue
502, 503, 504 Telegram or network troubleRetry 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 icon bot or blocked it. This is permanent until they act.

Groups and channels

  • Bot ignores messages: safety icon 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_id to 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_query within 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.
  • initData empty: the page was opened outside Telegram.
  • Validation fails: wrong secret formula. See initData validation.

A debugging routine

  1. Reproduce with a second account. See testing.
  2. Log the full error object, without secrets.
  3. Check getMe and getWebhookInfo.
  4. Reduce the request to the smallest failing call.
  5. Compare with an example in the documentation.
  6. 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 channel megaphone icon channels.

Related guides

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Common Telegram Bot Errors and How to Fix Them | TSocial