Ошибки Telegram Bot API: что значат 400, 401, 403, 409 и 429
Что значат ошибки Telegram Bot API: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 409 Conflict и 429 Too Many Requests с retry_after. Поля ответа, причины и что делать в каждом случае.
Если запрос к Telegram Bot API не удался, в ответе придёт JSON с "ok": false, числом в поле error_code и текстом в поле description. Обычно код совпадает с HTTP-статусом: 400 — запрос неверный, 401 — токен не подошёл, 403 — боту нельзя это делать, 409 — конфликт способов получения событий, 429 — слишком много запросов. Опираться стоит на description и на необязательное поле parameters: сама документация предупреждает, что содержание error_code в будущем может измениться.
Как выглядит ошибка
Пример ответа на слишком частые запросы:
{"ok":false,"error_code":429,"description":"Too Many Requests: retry after 5","parameters":{"retry_after":5}}
Поле parameters есть не у каждой ошибки. По документации Bot API, это объект ResponseParameters из двух необязательных полей, которые помогают обработать ошибку автоматически:
retry_after— через сколько секунд можно повторить запрос после превышения лимита;migrate_to_chat_id— идентификатор супергруппы, в которую превратилась обычная группа.
Тексты ошибок ниже взяты из документации и из открытого исходного кода сервера Bot API (telegram-bot-api). Если вы пишете бота на готовой библиотеке, она превращает такие ответы в исключения: например, в python-telegram-bot это Forbidden, Conflict и RetryAfter, в aiogram — TelegramForbiddenError, TelegramConflictError и TelegramRetryAfter.
Частые ошибки
| Код и описание | Что значит | Что делать |
|---|---|---|
400 Bad Request: chat not found | Бот не знает такого чата: опечатка в chat_id, либо человек ещё не писал боту, либо бота нет в этом чате | Проверьте chat_id. В личный чат бот может писать, только если человек его запускал |
400 Bad Request: message is not modified: ... | Вы редактируете сообщение, а новый текст и кнопки в точности совпадают с нынешними | Не отправляйте правку, если ничего не изменилось |
400 Bad Request: query is too old and response timeout expired or query ID is invalid | На нажатие кнопки отвечают слишком поздно или с неверным идентификатором | Отвечайте на callback_query методом answerCallbackQuery сразу после получения |
400 Bad Request: group chat was upgraded to a supergroup chat | Группа стала супергруппой, и у неё новый идентификатор | Возьмите новый идентификатор из parameters.migrate_to_chat_id и используйте его |
400 про разметку (can't parse entities и подобные) | Текст не соответствует parse_mode: не закрыт тег или не экранированы специальные символы | Исправьте или экранируйте разметку, правила — в разделе Formatting options документации |
400 Can't parse ... JSON object | Параметр, который должен быть JSON (например, кнопки), записан неверно | Проверьте JSON и его кодировку |
401 Unauthorized | Токен неверный или заменён | Проверьте токен методом getMe: как это сделать |
403 Forbidden: bot was blocked by the user | Человек заблокировал бота | Не пишите ему больше; отметьте его у себя как недоступного |
403 Forbidden: user is deactivated | Аккаунт получателя удалён | То же: сообщение доставить нельзя |
403 Forbidden: bot was kicked from the group chat (или supergroup chat, channel chat) | Бота удалили из группы, супергруппы или канала | Перестаньте слать туда сообщения |
404 Not Found: method not found | Такого метода нет: опечатка в названии | Сверьте название в документации |
409 Conflict: ... | Одновременно работают два способа получать события | См. раздел ниже |
429 Too Many Requests: retry after N | Превышен лимит запросов | Подождите N секунд (поле retry_after) и повторите |
500 Internal Server Error | Сбой на стороне сервера | Повторите запрос позже |
409 Conflict: два способа получать события
Telegram отдаёт события боту только одному получателю. Ошибка 409 бывает в трёх случаях:
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running— одного и того же бота одновременно опрашивают два процесса. Типично это копия бота на сервере и на вашем компьютере или перезапуск, при котором прежний процесс не успел завершиться. Оставьте один работающий экземпляр.Conflict: terminated by setWebhook request— во время опросаgetUpdatesвызвалиsetWebhook.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first—getUpdatesвызван, а у бота задан webhook. Удалите его методомdeleteWebhook.
Подробнее про оба способа — в статье getUpdates и webhook.
429 и лимиты: как не упереться
По FAQ для разработчиков ботов, в одном чате не стоит отправлять больше одного сообщения в секунду: небольшие всплески допускаются, но потом приходят ошибки 429. В группе бот не может отправлять больше 20 сообщений в минуту, а при массовых уведомлениях — больше примерно 30 сообщений в секунду. Для больших рассылок в Telegram есть платные рассылки, их включают в @BotFather: условия и стоимость — в документации Bot API и FAQ. Без них Telegram советует растянуть рассылку на более долгий срок, например на 8–12 часов.
Что делать при 429:
- Прочитайте
parameters.retry_after. - Подождите столько секунд и повторите запрос.
- Ставьте сообщения в очередь с паузой, а не отправляйте всё разом.
Что делать с ошибкой
- Всегда проверяйте
ok. Если онfalse, читайтеdescription: по тексту можно понять причину. - Ошибки 400, 401 и 403 повтором не исправить: запрос нужно поправить или перестать отправлять. Исключение — 429: после паузы повторяйте.
- Журнал ошибок записывайте вместе с текстом
description: по одному коду причину не определить. Не записывайте в журнал адрес запроса целиком, ведь в нём лежит токен. - Чтобы увидеть код ответа в командной строке, добавьте
-i:curl -i "https://api.telegram.org/bot<ТОКЕН>/getMe". Как отправить сообщение запросом, показано в статье про curl.
Что дальше
Бот надёжнее, когда события приходят без пропусков: getUpdates и webhook. Первое сообщение через API — sendMessage через curl. Токен и его защита — в отдельной статье, а размещение бота на сервере — в статье про хостинг.
Частые вопросы
Что значит ошибка Telegram API?
Это ответ Bot API с "ok": false: в error_code числовой код, в description причина, а иногда ещё parameters с подсказкой вроде retry_after. Причину читайте в description.
Что значит ошибка 403 Forbidden: bot was blocked by the user?
Человек заблокировал бота, и написать ему нельзя. Повтор не поможет. Он снова сможет получать сообщения, только если разблокирует бота.
Как исправить ошибку 409 Conflict в боте Telegram?
Запустите только один экземпляр бота. Если ошибка сообщает про webhook, удалите его методом deleteWebhook или перестаньте вызывать getUpdates.
Что делать при ошибке 429 Too Many Requests?
Подождите столько секунд, сколько указано в retry_after, и повторите запрос. Чтобы не получать её снова, отправляйте не больше одного сообщения в секунду в один чат и не больше 20 в минуту в группу.
Почему бот возвращает 401 Unauthorized?
Токен неверный или заменён. Проверьте его методом getMe и, если нужно, получите новый у @BotFather.
Что значит 400 Bad Request: chat not found?
Бот не нашёл чат: проверьте chat_id, и убедитесь, что человек запускал бота, а бот состоит в группе или канале.
