Ошибки Telegram Bot API: что означает каждая ошибка и как её исправить
Ошибки Telegram Bot API приходят в виде JSON с "ok": false, числовым error_code (400, 403, 429 и т. д.) и текстовым description вроде Bad Request: chat not found. У большинства из них одна из десятка типичных причин: неверный chat id, пользователь заблокировал бота, запущен второй экземпляр бота или сообщений в секунду слишком много. Ниже — формат ответа, таблица частых ошибок с решениями по кодам и готовый код обработки на Python и JavaScript, который учитывает retry_after и migrate_to_chat_id.
Формат ответа с ошибкой
Любой ответ Bot API — это JSON-объект с булевым полем ok. При успехе данные лежат в result, при ошибке ответ выглядит так:
{
"ok": false,
"error_code": 400,
"description": "Bad Request: chat not found"
}
| Поле | Значение |
|---|---|
ok | false для любого неудачного запроса. |
error_code | Целое число, повторяет HTTP-статус: 400, 401, 403, 404, 409, 413, 429, 5xx. |
description | Текстовое пояснение, обычно с префиксом статуса: Bad Request:, Forbidden:, Conflict:. |
parameters | Необязательный объект ResponseParameters, который помогает обработать ошибку автоматически: retry_after (сколько секунд ждать после flood control) и migrate_to_chat_id (новый id группы, ставшей супергруппой). |
Два ответа с parameters, которые стоит обрабатывать в коде:
{"ok": false, "error_code": 429, "description": "Too Many Requests: retry after 35", "parameters": {"retry_after": 35}}
{"ok": false, "error_code": 400, "description": "Bad Request: group chat was upgraded to a supergroup chat", "parameters": {"migrate_to_chat_id": -1001234567890}}
Не стройте логику на тексте description
Полного списка сообщений об ошибках Bot API Telegram не публикует. Описания в этом гайде — тексты, которые API возвращает сейчас, но это обычный текст для людей, и он может измениться без предупреждения. В официальной документации даже сказано, что содержимое error_code может измениться в будущем. Поэтому надёжный бот:
- в первую очередь ветвится по
error_code(400, 403, 429, 5xx); - опирается на
parameters.retry_afterиparameters.migrate_to_chat_id, если они есть, а не вытаскивает числа из текста; - сравнивает подстроки описания только там, где нужно различить ошибки с одинаковым кодом, — без учёта регистра и с безопасной веткой «по умолчанию»;
- пишет в лог полный
description, чтобы новые тексты ошибок были видны, а не терялись.
400 Bad Request: частые ошибки Telegram
Ошибка 400 Bad Request в Telegram означает, что запрос дошёл до API, но в нём что-то не так: параметр, целевой чат или состояние сообщения.
| Описание | Причина | Решение |
|---|---|---|
chat not found | Неверный chat_id, id группы без -100, пользователь не запускал бота, бота нет в группе или канале, либо id из боевого Telegram используется на тестовом сервере. | Напишите боту (или добавьте его в чат) и скопируйте id из getUpdates; подробнее — в гайде про chat id. |
PEER_ID_INVALID | id некорректен или указывает на чат, с которым бот никогда не взаимодействовал. | Как и при chat not found: возьмите свежий id из апдейта. |
message is not modified | Метод редактирования вызван с теми же текстом и разметкой, что уже есть у сообщения. Типично, когда пользователь дважды жмёт одну кнопку. | Сравнивайте перед редактированием или ловите и игнорируйте эту ошибку. |
message to edit not found | Неверная пара message_id/chat_id или сообщение удалено. | Сохраняйте message_id из ответа метода отправки вместе с id чата. |
message can't be edited | Сообщение отправил не бот, или его уже нельзя редактировать. | Отправьте новое сообщение вместо редактирования. |
can't parse entities: … | Сломана разметка parse_mode: неэкранированный < или & в HTML либо один из символов _ * [ ] ( ) ~ ` > # + - = | { } . ! без экранирования в MarkdownV2. Текст после двоеточия указывает смещение в байтах. | Экранируйте пользовательский текст или отправляйте его без parse_mode. |
message text is empty | text отсутствует или пуст, часто это JSON-тело без Content-Type: application/json. | Проверьте значение и кодировку запроса. |
wrong file identifier/HTTP URL specified | file_id другого бота (file id привязаны к одному боту) или URL, который Telegram не может скачать либо который превышает лимиты загрузки по ссылке (5 МБ для фото, 20 МБ для остальных файлов). | Загрузите файл заново через multipart/form-data или дайте публичную прямую ссылку. |
query is too old and response timeout expired or query ID is invalid | answerCallbackQuery или answerInlineQuery вызван слишком поздно, повторно или с неверным id. | Отвечайте в самом начале обработчика, до долгой работы; после перезапуска пропускайте устаревшие callback-запросы. |
not enough rights to send text messages to the chat (фото, документы…) | Бот ограничен в группе или не имеет прав на публикацию в канале. | Выдайте боту нужное разрешение или права администратора. |
group chat was upgraded to a supergroup chat | Обычная группа стала супергруппой и получила новый id, он приходит в parameters.migrate_to_chat_id. | Сохраните новый id и повторите запрос с ним. |
BUTTON_DATA_INVALID и другие ошибки reply markup | callback_data вне диапазона 1–64 байт (кириллический символ занимает 2 байта) или некорректный reply_markup. | Храните длинные данные на сервере, а в callback_data кладите короткий ключ. |
member list is inaccessible | Метод для работы с участниками вызван там, где бот не может читать список участников, обычно в канале, где он не администратор. | Сделайте бота администратором или не запрашивайте участников в этом чате. |
Чтобы безопасно воспроизвести ошибку, откройте sendMessage в Bot API Tester, укажите выдуманный chat_id и посмотрите на «сырой» JSON-ответ.
401 Unauthorized и 404 Not Found
401 Unauthorized: токен неверный или отозван. Бывает и тогда, когда боевой токен отправляют на тестовый сервер или наоборот. Проверьте токен черезgetMe; если он утёк и был отозван, возьмите новый в @BotFather.404 Not Found: URL не соответствует форматуhttps://api.telegram.org/bot<token>/METHOD_NAME. Типичные причины: нет префиксаbotперед токеном, в токене пробелы или перенос строки, опечатка в имени метода. Имена методов не чувствительны к регистру, поэтомуsendmessageработает, аsendMesage— нет.
403 Forbidden: bot was blocked by the user и похожие ошибки
Ошибка 403 означает, что боту нельзя писать в этот чат. Повтор запроса не поможет — обновите данные у себя.
| Описание | Что произошло | Что делать |
|---|---|---|
bot was blocked by the user | Пользователь заблокировал или остановил бота. | Пометьте пользователя неактивным и перестаньте ему писать. В личных чатах бот также получает апдейт my_chat_member при блокировке и разблокировке. |
bot can't initiate conversation with a user | Пользователь ни разу не открывал бота. Боты не могут писать первыми. | Попросите пользователя нажать «Запустить», например по ссылке t.me/your_bot. |
bot is not a member of the channel chat | Бота нет в канале. | Добавьте бота в канал администратором с правом публикации. |
bot was kicked from the group chat | Бота удалили из группы (для супергруппы текст упоминает supergroup chat). | Уберите чат из списка рассылки или попросите админа вернуть бота. |
user is deactivated | Аккаунт удалён. | Удалите пользователя из рассылки. |
409 Conflict в getUpdates
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running— с одним токеном опрашивают API два процесса: забытый терминал, второй контейнер, деплой, который стартовал до остановки старой версии. Оставьте ровно один поллер на токен.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first— у бота установлен вебхук, а getUpdates при нём не работает. ВызовитеdeleteWebhookили оставьте вебхук и откажитесь от поллинга.
Ошибки 413, 429 и 5xx
413 Request Entity Too Large: загружаемый файл больше, чем принимает API. Черезapi.telegram.orgботы загружают файлы до 50 МБ; локальный Bot API сервер поднимает лимит до 2000 МБ.429 Too Many Requests: retry after N: сработал flood control. Подождитеparameters.retry_afterсекунд и повторите. Затем снизьте темп: около 1 сообщения в секунду в один чат, 20 в минуту в группу, примерно 30 в секунду суммарно. Цифры и стратегии очередей — в гайде про лимиты.500,502 Bad Gatewayи другие 5xx: проблема на стороне Telegram или по пути к нему. Повторяйте с экспоненциальной задержкой. Тело ответа 502 может быть не JSON, поэтому не рассчитывайте, чтоresponse.json()всегда сработает.
Код обработки ошибок с retry_after и migrate_to_chat_id
Эта обёртка повторяет запрос после 429 через retry_after, переходит на migrate_to_chat_id, делает паузы при 5xx и сетевых ошибках, а для остальных случаев выбрасывает типизированное исключение — решение принимает вызывающий код. На Python нужен requests; версия на JavaScript требует Node.js 18+ и запускается как файл .mjs.
import os
import time
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
class TelegramError(Exception):
def __init__(self, method, code, description, parameters=None):
super().__init__(f"{method}: {code} {description}")
self.code = code
self.description = description
self.parameters = parameters or {}
def call(method, max_retries=5, **params):
for attempt in range(max_retries):
try:
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
except (requests.RequestException, ValueError):
# сетевая ошибка или ответ не в JSON (например, HTML-страница 502)
time.sleep(2 ** attempt)
continue
if data.get("ok"):
return data["result"]
code = data.get("error_code")
extra = data.get("parameters") or {}
if "retry_after" in extra: # 429 flood control: ждём, сколько сказано
time.sleep(extra["retry_after"])
continue
if "migrate_to_chat_id" in extra and "chat_id" in params:
print(f"chat {params['chat_id']} migrated to {extra['migrate_to_chat_id']}: update your database")
params["chat_id"] = extra["migrate_to_chat_id"]
continue
if code is not None and code >= 500: # проблема на стороне Telegram: пауза
time.sleep(2 ** attempt)
continue
raise TelegramError(method, code, data.get("description", ""), extra)
raise TelegramError(method, None, "gave up after retries")
def notify(chat_id, text):
try:
return call("sendMessage", chat_id=chat_id, text=text)
except TelegramError as e:
if e.code == 403:
# заблокирован, удалён из чата или аккаунт удалён: больше не пишем сюда
print(f"chat {chat_id} is unreachable: {e.description}")
elif e.code == 400 and "chat not found" in e.description.lower():
print(f"wrong chat id {chat_id}")
else:
raise
notify(123456789, "Hello!")const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
class TelegramError extends Error {
constructor(method, code, description, parameters = {}) {
super(`${method}: ${code} ${description}`);
this.code = code;
this.description = description;
this.parameters = parameters;
}
}
async function call(method, params = {}, maxRetries = 5) {
params = { ...params };
for (let attempt = 0; attempt < maxRetries; attempt++) {
let data;
try {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
data = await res.json();
} catch {
// сетевая ошибка или ответ не в JSON (например, HTML-страница 502)
await sleep(2 ** attempt);
continue;
}
if (data.ok) return data.result;
const code = data.error_code;
const extra = data.parameters ?? {};
if (extra.retry_after !== undefined) { // 429 flood control: ждём, сколько сказано
await sleep(extra.retry_after);
continue;
}
if (extra.migrate_to_chat_id !== undefined && "chat_id" in params) {
console.log(`chat ${params.chat_id} migrated to ${extra.migrate_to_chat_id}: update your database`);
params.chat_id = extra.migrate_to_chat_id;
continue;
}
if (code >= 500) { // проблема на стороне Telegram: пауза
await sleep(2 ** attempt);
continue;
}
throw new TelegramError(method, code, data.description ?? "", extra);
}
throw new TelegramError(method, null, "gave up after retries");
}
async function notify(chatId, text) {
try {
return await call("sendMessage", { chat_id: chatId, text });
} catch (err) {
if (!(err instanceof TelegramError)) throw err;
if (err.code === 403) {
// заблокирован, удалён из чата или аккаунт удалён: больше не пишем сюда
console.log(`chat ${chatId} is unreachable: ${err.description}`);
} else if (err.code === 400 && err.description.toLowerCase().includes("chat not found")) {
console.log(`wrong chat id ${chatId}`);
} else {
throw err;
}
}
}
await notify(123456789, "Hello!");Важная оговорка: запрос, который оборвался по таймауту на вашей стороне, мог всё же выполниться, поэтому повтор отправки после сетевой ошибки иногда доставляет сообщение дважды.
Чек-лист отладки
- Логируйте полный JSON каждого неудачного ответа:
error_code,descriptionиparameters. - Проверьте токен через getMe в Bot API Tester: 401 значит, что проблема в самом токене.
- При
chat not foundи ошибках 403 вызовитеgetUpdatesи сравните реальныйchat.idс тем, что указан в конфиге. - При 409 поищите второй запущенный экземпляр и проверьте
getWebhookInfo.
Связанные гайды: как узнать chat id в Telegram, отправка сообщений и экранирование в parse_mode, лимиты Telegram Bot API и обработка 429 и настройка вебхука.
Частые вопросы
Что значит «Bad Request: chat not found» в Telegram?
Бот не видит чат с указанным chat_id: id неверный или без префикса -100, пользователь ни разу не запускал бота, либо бота нет в группе или канале. Напишите боту и возьмите id из getUpdates.
Как обрабатывать «Forbidden: bot was blocked by the user»?
Со стороны бота это не исправить: пользователь заблокировал бота. Ловите код 403, помечайте пользователя неактивным в базе и не пишите ему, пока он сам снова не напишет боту.
Почему getUpdates возвращает 409 Conflict?
Либо с тем же токеном опрашивает API другой процесс (terminated by other getUpdates request), либо установлен вебхук (can't use getUpdates method while webhook is active). Остановите второй экземпляр или вызовите deleteWebhook.
Сколько ждать после 429 Too Many Requests?
Ровно столько секунд, сколько указано в parameters.retry_after, затем повторить запрос. Не повторяйте сразу и не зашивайте задержку в код: значение меняется от ответа к ответу.
Стоит ли проверять текст ошибки в коде?
Как можно меньше. description — текст для человека, и Telegram может его изменить. Сначала ветвитесь по error_code и parameters, а подстроки описания проверяйте без учёта регистра и только там, где нужно различить две ошибки с одним кодом.
Что означает 401 Unauthorized в Bot API?
Токен недействителен: опечатка, токен отозван в @BotFather или относится к другому окружению (боевое или тестовый сервер). Проверьте его через getMe и возьмите актуальный в /mybots → API Token.
Читайте также
Как создать бота в Телеграм: от @BotFather до первого сообщения
Как создать бота в Телеграм: регистрация в @BotFather, токен, проверка через getMe, первое сообщение на curl и Python, команды и описание бота.
Как задеплоить Telegram-бота: VPS, Docker и serverless-хостинг
Как задеплоить Telegram-бота: polling или вебхук, сервис systemd на VPS, Docker, Cloudflare Workers с secret_token и чек-лист перед запуском.
Что нового в Telegram Bot API 10.0–10.5: настройки бота, виджеты, rich-сообщения, эфемерные сообщения и гостевой режим
Что нового в Telegram Bot API 10.0–10.5: setMySettings и BotFullInfo, HTML-виджеты, rich- и эфемерные сообщения, гостевой режим — с примерами.
Лимиты Telegram Bot API: сообщения в секунду, ошибка 429 и размеры файлов
Все лимиты Telegram Bot API в одном месте: сообщения в секунду, ошибка 429 и retry_after, платные рассылки, размеры файлов, длина текста и подписи.
Команды Telegram-бота: setMyCommands, области видимости и deep link для /start
Настройка команд Telegram-бота: /setcommands в @BotFather, setMyCommands с областями и языками, параметр /start в deep link и команды /cmd@bot в группах.
Клавиатуры Telegram-бота: инлайн-кнопки, callback_data и reply-клавиатура
Кнопки Telegram-бота: инлайн-клавиатура с callback_data, answerCallbackQuery, редактирование сообщения после нажатия, reply-клавиатура и ForceReply.
Интеграция n8n и Telegram: подключение бота, Telegram Trigger и отправка сообщений
Как подключить Telegram к n8n: токен бота в Access Token, вебхук Telegram Trigger по публичному HTTPS, отправка сообщений по chat id и разбор ошибок.
Как отправить сообщение через бота Telegram: sendMessage, разметка и кнопки
Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.
Токен бота Telegram: как получить, где найти, как проверить и отозвать
Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.
Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление
Как настроить вебхук Телеграм-бота: требования к HTTPS и портам, setWebhook с secret_token, проверка через getWebhookInfo, удаление и частые ошибки.
Как узнать chat id в Telegram: пользователь, группа, канал и тема форума
Как узнать chat id в Telegram через getUpdates: личный чат, группа, супергруппа, канал и тема форума. Форматы id с -100 и что делать с пустым result.
Инлайн-бот Telegram: как включить inline mode и отвечать на инлайн-запросы
Как сделать инлайн-бота Telegram: включить inline mode через @BotFather или setMySettings, обработать inline_query и ответить через answerInlineQuery.
Оплата Telegram Stars в боте: счета, pre-checkout, возвраты и подписки
Приём оплаты в Telegram Stars в боте: sendInvoice с XTR, pre_checkout_query, successful_payment, возвраты, подписки и пример на Python и JS.
Тестовый сервер Telegram: как тестировать бота в тестовом окружении
Тестовый сервер Telegram для ботов: вход в тестовое окружение, создание тестового бота, запросы к Bot API через /test/ и переключатель TEST в тестере.
Виджеты Telegram для сайта: вход через Telegram, встраивание постов, комментарии и кнопка «Поделиться»
Вход через Telegram на сайте: новый Telegram Login (OIDC), старый Login Widget с проверкой hash, встраивание постов, комментарии и кнопка «Поделиться».
TelegramWidget JavaScript API: свойства, события, коды ошибок и лимиты
Справочник TelegramWidget API: свойства, request(), события, коды ошибок, CSS-переменные, widget_query и answerWidgetQuery, а также все лимиты виджетов.
Примеры виджетов Telegram: готовый HTML и код бота на Python
Рабочие примеры виджетов Telegram с полным кодом: карточка заказа, счётчик с запросами widget_query, общий живой опрос и заглушка для превью в браузере.
Виджеты Telegram: интерактивный HTML прямо в сообщениях бота
Виджеты Telegram в Bot API 10.4: что это, как работают sendWidget, chat_data и public_data, где виджеты доступны сейчас и чем они отличаются от Mini Apps.
Тестирование Telegram Mini App: от браузера до отладки на телефоне
Тестирование Telegram Mini App по шагам: mock-режим в браузере, HTTPS-туннель для localhost, тестовая среда, DevTools на телефоне и проверка initData.