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, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.

Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати

Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.

Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення

Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.

Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму

Як дізнатися chat id у Телеграм через 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.