Telegram Bot API

Ошибки Telegram Bot API: что означает каждая ошибка и как её исправить

· 9 мин чтения

Ошибки 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"
}
ПолеЗначение
okfalse для любого неудачного запроса.
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 может измениться в будущем. Поэтому надёжный бот:

400 Bad Request: частые ошибки Telegram

Ошибка 400 Bad Request в Telegram означает, что запрос дошёл до API, но в нём что-то не так: параметр, целевой чат или состояние сообщения.

ОписаниеПричинаРешение
chat not foundНеверный chat_id, id группы без -100, пользователь не запускал бота, бота нет в группе или канале, либо id из боевого Telegram используется на тестовом сервере.Напишите боту (или добавьте его в чат) и скопируйте id из getUpdates; подробнее — в гайде про chat id.
PEER_ID_INVALIDid некорректен или указывает на чат, с которым бот никогда не взаимодействовал.Как и при 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 emptytext отсутствует или пуст, часто это JSON-тело без Content-Type: application/json.Проверьте значение и кодировку запроса.
wrong file identifier/HTTP URL specifiedfile_id другого бота (file id привязаны к одному боту) или URL, который Telegram не может скачать либо который превышает лимиты загрузки по ссылке (5 МБ для фото, 20 МБ для остальных файлов).Загрузите файл заново через multipart/form-data или дайте публичную прямую ссылку.
query is too old and response timeout expired or query ID is invalidanswerCallbackQuery или 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 markupcallback_data вне диапазона 1–64 байт (кириллический символ занимает 2 байта) или некорректный reply_markup.Храните длинные данные на сервере, а в callback_data кладите короткий ключ.
member list is inaccessibleМетод для работы с участниками вызван там, где бот не может читать список участников, обычно в канале, где он не администратор.Сделайте бота администратором или не запрашивайте участников в этом чате.

Чтобы безопасно воспроизвести ошибку, откройте sendMessage в Bot API Tester, укажите выдуманный chat_id и посмотрите на «сырой» JSON-ответ.

401 Unauthorized и 404 Not Found

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

Ошибки 413, 429 и 5xx

Код обработки ошибок с 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!");

Важная оговорка: запрос, который оборвался по таймауту на вашей стороне, мог всё же выполниться, поэтому повтор отправки после сетевой ошибки иногда доставляет сообщение дважды.

Чек-лист отладки

  1. Логируйте полный JSON каждого неудачного ответа: error_code, description и parameters.
  2. Проверьте токен через getMe в Bot API Tester: 401 значит, что проблема в самом токене.
  3. При chat not found и ошибках 403 вызовите getUpdates и сравните реальный chat.id с тем, что указан в конфиге.
  4. При 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.