TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram
TSocial planet logoTelesocial

Telesocial › Cheat sheets

Bot Error Code Cheat Sheet

Cheat sheets · 2026-11-06 · 18+ readers

Read error_code and description before anything else. Then use this lookup.

By code

CodeMeaningFirst thing to try
400Bad requestRead the description for the field at fault
401UnauthorizedCheck or replace the token
403ForbiddenThe user blocked the bot or rights are missing
404Not foundCheck the method name and URL
409ConflictOne poller only, and no webhook while polling
429Too many requestsWait retry_after seconds
5xxServer troubleRetry with backoff

By phrase

  • chat not found: wrong id, or the user never pressed Start.
  • can't parse entities: escape your HTML or drop parse_mode.
  • message is too long: stay under 4096 characters.
  • message is not modified: your edit changed nothing.
  • query is too old: answer callbacks within seconds.
  • bot icon bot was blocked by the user: mark inactive and stop.

A debug ritual

  1. Log the full error object without secrets.
  2. Call getMe and getWebhookInfo.
  3. Shrink the request until it works.
  4. Test with a second account.

Frequently asked questions

Which errors should I retry?

Network errors, 429 and 5xx, with backoff.

Why does it work for me but not for users?

You are the owner with extra rights. Test as a stranger.

Is there an official full list?

Not a complete one. Use the description text and the Bot code icon API FAQ.

More cheat sheets

Bot Error Code Cheat Sheet | Telesocial