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
| Code | Meaning | First thing to try |
|---|---|---|
| 400 | Bad request | Read the description for the field at fault |
| 401 | Unauthorized | Check or replace the token |
| 403 | Forbidden | The user blocked the bot or rights are missing |
| 404 | Not found | Check the method name and URL |
| 409 | Conflict | One poller only, and no webhook while polling |
| 429 | Too many requests | Wait retry_after seconds |
| 5xx | Server trouble | Retry 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 was blocked by the user: mark inactive and stop.
A debug ritual
- Log the full error object without secrets.
- Call
getMeandgetWebhookInfo. - Shrink the request until it works.
- 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 API FAQ.