# Ошибки Telegram Bot API: что значат 400, 401, 403, 409 и 429

Как устроен ответ с ошибкой, разбор кодов 400, 401, 403, 409 и 429 и что делать при каждой.

https://shiba-bank.com/ru/guides/bot-api-errors

Обновлено 02.10.2026 · 6 мин чтения

Если запрос к 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](https://core.telegram.org/bots/api), это объект `ResponseParameters` из двух необязательных полей, которые помогают обработать ошибку автоматически:

- `retry_after` — через сколько секунд можно повторить запрос после превышения лимита;
- `migrate_to_chat_id` — идентификатор супергруппы, в которую превратилась обычная группа.

Тексты ошибок ниже взяты из документации и из открытого исходного кода сервера Bot API ([telegram-bot-api](https://github.com/tdlib/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`: [как это сделать](https://shiba-bank.com/ru/guides/bot-token) |
| 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](https://shiba-bank.com/ru/guides/bot-api-updates).

## 429 и лимиты: как не упереться

По [FAQ для разработчиков ботов](https://core.telegram.org/bots/faq), в одном чате не стоит отправлять больше одного сообщения в секунду: небольшие всплески допускаются, но потом приходят ошибки 429. В группе бот не может отправлять больше 20 сообщений в минуту, а при массовых уведомлениях — больше примерно 30 сообщений в секунду. Для больших рассылок в Telegram есть платные рассылки, их включают в @BotFather: условия и стоимость — в [документации Bot API](https://core.telegram.org/bots/api) и FAQ. Без них Telegram советует растянуть рассылку на более долгий срок, например на 8–12 часов.

Что делать при 429:

1. Прочитайте `parameters.retry_after`.
2. Подождите столько секунд и повторите запрос.
3. Ставьте сообщения в очередь с паузой, а не отправляйте всё разом.

## Что делать с ошибкой

- Всегда проверяйте `ok`. Если он `false`, читайте `description`: по тексту можно понять причину.
- Ошибки 400, 401 и 403 повтором не исправить: запрос нужно поправить или перестать отправлять. Исключение — 429: после паузы повторяйте.
- Журнал ошибок записывайте вместе с текстом `description`: по одному коду причину не определить. Не записывайте в журнал адрес запроса целиком, ведь в нём лежит токен.
- Чтобы увидеть код ответа в командной строке, добавьте `-i`: `curl -i "https://api.telegram.org/bot<ТОКЕН>/getMe"`. Как отправить сообщение запросом, [показано в статье про curl](https://shiba-bank.com/ru/guides/bot-api-curl).

## Что дальше

Бот надёжнее, когда события приходят без пропусков: [getUpdates и webhook](https://shiba-bank.com/ru/guides/bot-api-updates). Первое сообщение через API — [sendMessage через curl](https://shiba-bank.com/ru/guides/bot-api-curl). Токен и его защита — [в отдельной статье](https://shiba-bank.com/ru/guides/bot-token), а размещение бота на сервере — [в статье про хостинг](https://shiba-bank.com/ru/guides/bot-hosting).

## Частые вопросы

### Что значит ошибка 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](https://t.me/botfather).

### Что значит 400 Bad Request: chat not found?
Бот не нашёл чат: проверьте `chat_id`, и убедитесь, что человек запускал бота, а бот состоит в группе или канале.