Помилки 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, розмітка й кнопки
Як надіслати повідомлення через бота телеграм: 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.