Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục
Lỗi Telegram Bot API được trả về dưới dạng JSON với "ok": false, mã số error_code như 400, 403 hay 429, và description dạng chữ như Bad Request: chat not found. Phần lớn lỗi rơi vào khoảng một chục nguyên nhân quen thuộc: sai chat id, người dùng đã chặn bot, chạy hai instance bot, hoặc gửi quá nhiều tin mỗi giây. Dưới đây là định dạng phản hồi lỗi, bảng các lỗi thường gặp kèm cách sửa theo từng mã, và code xử lý bằng Python và JavaScript có tôn trọng retry_after và migrate_to_chat_id.
Định dạng phản hồi lỗi
Mọi phản hồi của Bot API là một object JSON có trường Boolean ok. Khi thành công, dữ liệu nằm trong result; khi thất bại, bạn nhận được:
{
"ok": false,
"error_code": 400,
"description": "Bad Request: chat not found"
}
| Trường | Ý nghĩa |
|---|---|
ok | false với mọi request thất bại. |
error_code | Số nguyên, trùng với HTTP status: 400, 401, 403, 404, 409, 413, 429, 5xx. |
description | Giải thích dạng văn bản, thường có tiền tố là tên status: Bad Request:, Forbidden:, Conflict:. |
parameters | ResponseParameters tùy chọn, giúp xử lý lỗi tự động: retry_after (số giây cần chờ sau flood control) và migrate_to_chat_id (id mới của group đã nâng cấp thành supergroup). |
Hai phản hồi có parameters mà code của bạn nên xử lý:
{"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}}
Đừng xây logic dựa trên nội dung description
Telegram không công bố danh sách đầy đủ các thông báo lỗi của Bot API. Các description trong bài là văn bản API đang trả về hiện nay, nhưng chúng chỉ là chữ cho người đọc và có thể thay đổi mà không báo trước. Tài liệu chính thức còn nói nội dung của error_code cũng có thể thay đổi. Vì vậy một bot chắc chắn sẽ:
- rẽ nhánh theo
error_codetrước (400, 403, 429, 5xx); - dựa vào
parameters.retry_aftervàparameters.migrate_to_chat_idkhi có, thay vì tách số từ description; - chỉ so khớp chuỗi con của description khi phải phân biệt các lỗi cùng mã, không phân biệt hoa thường, và có nhánh dự phòng an toàn khi không khớp;
- ghi log toàn bộ description, để thông báo mới hiện ra trong log thay vì bị nuốt mất.
400 Bad Request: các lỗi Telegram thường gặp
Lỗi 400 Bad Request của Telegram nghĩa là request đã tới API nhưng có gì đó sai: một tham số, chat đích hoặc trạng thái của tin nhắn.
| Description | Nguyên nhân | Cách sửa |
|---|---|---|
chat not found | Sai chat_id, id group thiếu -100, người dùng chưa từng start bot, bot không ở trong group hoặc kênh, hoặc dùng id production trên server test. | Nhắn cho bot (hoặc thêm bot vào chat) rồi copy id từ getUpdates; xem bài về chat id. |
PEER_ID_INVALID | Id sai định dạng hoặc trỏ tới chat mà bot chưa từng tương tác. | Giống chat not found: lấy id mới từ một update. |
message is not modified | Gọi method sửa với đúng văn bản và reply markup mà tin nhắn đang có. Hay gặp khi người dùng bấm cùng một nút hai lần. | So sánh trước khi sửa, hoặc bắt và bỏ qua lỗi này. |
message to edit not found | Cặp message_id/chat_id sai, hoặc tin nhắn đã bị xóa. | Lưu message_id do method gửi trả về cùng với chat id của nó. |
message can't be edited | Tin nhắn không do bot gửi, hoặc không còn sửa được nữa. | Gửi tin mới thay vì sửa. |
can't parse entities: … | Markup parse_mode bị hỏng: < hoặc & chưa escape trong HTML, hoặc một trong các ký tự _ * [ ] ( ) ~ ` > # + - = | { } . ! chưa escape trong MarkdownV2. Phần sau dấu hai chấm chỉ ra vị trí byte. | Escape văn bản do người dùng nhập, hoặc gửi không kèm parse_mode. |
message text is empty | Thiếu text hoặc rỗng, thường do gửi body JSON mà không có Content-Type: application/json. | Kiểm tra giá trị và cách mã hóa request. |
wrong file identifier/HTTP URL specified | file_id của bot khác (file id gắn với một bot), hoặc URL mà Telegram không tải được hay vượt giới hạn gửi qua URL (5 MB với ảnh, 20 MB với file khác). | Upload lại file bằng multipart/form-data, hoặc dùng link trực tiếp công khai. |
query is too old and response timeout expired or query ID is invalid | Gọi answerCallbackQuery hoặc answerInlineQuery quá muộn, hai lần, hoặc với id sai. | Trả lời ngay đầu handler, trước phần việc chậm; sau khi khởi động lại, bỏ qua các callback query cũ. |
not enough rights to send text messages to the chat (ảnh, tài liệu…) | Bot bị hạn chế trong group hoặc không có quyền đăng bài trong kênh. | Cấp cho bot quyền cần thiết hoặc quyền admin. |
group chat was upgraded to a supergroup chat | Group thường đã thành supergroup và có id mới, trả về trong parameters.migrate_to_chat_id. | Lưu id mới và gửi lại request với id đó. |
BUTTON_DATA_INVALID và các lỗi reply markup khác | callback_data nằm ngoài 1–64 byte (ký tự không phải Latin, kể cả chữ có dấu, chiếm 2–4 byte), hoặc reply_markup sai cấu trúc. | Lưu dữ liệu dài trên server và chỉ đặt một khóa ngắn vào callback_data. |
member list is inaccessible | Gọi method liên quan tới thành viên ở nơi bot không đọc được danh sách thành viên, thường là kênh mà bot không phải admin. | Cho bot làm admin, hoặc không truy vấn thành viên ở đó. |
Muốn tái hiện lỗi một cách an toàn, hãy mở sendMessage trong Bot API Tester, nhập một chat_id bịa ra và xem phản hồi JSON gốc.
401 Unauthorized và 404 Not Found
401 Unauthorized: token sai hoặc đã bị thu hồi. Lỗi này cũng xảy ra khi gửi token production tới server test hoặc ngược lại. Kiểm tra token bằnggetMe; nếu token bị lộ và đã thu hồi, hãy lấy token mới từ @BotFather.404 Not Found: URL không khớphttps://api.telegram.org/bot<token>/METHOD_NAME. Nguyên nhân thường gặp: thiếu tiền tốbottrước token, token dính dấu cách hoặc xuống dòng, hoặc gõ sai tên method. Tên method không phân biệt hoa thường nênsendmessagevẫn chạy, nhưngsendMesagethì không.
403 Forbidden: bot was blocked by the user và các lỗi tương tự
Lỗi 403 nghĩa là bot không được phép nhắn vào chat này. Thử lại không giúp gì; hãy cập nhật dữ liệu của bạn.
| Description | Chuyện gì đã xảy ra | Cần làm gì |
|---|---|---|
bot was blocked by the user | Người dùng đã chặn hoặc dừng bot. | Đánh dấu người dùng không hoạt động và ngừng nhắn cho họ. Trong chat riêng, bot cũng nhận update my_chat_member khi bị chặn hoặc bỏ chặn. |
bot can't initiate conversation with a user | Người dùng chưa từng mở bot. Bot không thể nhắn trước. | Nhờ người dùng bấm Start, ví dụ qua link t.me/your_bot. |
bot is not a member of the channel chat | Bot không ở trong kênh. | Thêm bot vào kênh làm admin có quyền đăng bài. |
bot was kicked from the group chat | Bot đã bị xóa khỏi group (với supergroup, thông báo sẽ nhắc tới supergroup chat). | Bỏ chat khỏi danh sách hoặc nhờ admin thêm lại bot. |
user is deactivated | Tài khoản đã bị xóa. | Xóa người dùng khỏi danh sách gửi tin. |
409 Conflict trong getUpdates
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running— hai tiến trình cùng polling với một token: một terminal bị quên, container thứ hai, hay bản deploy mới khởi động trước khi bản cũ dừng. Mỗi token chỉ giữ đúng một tiến trình polling.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first— bot đang có webhook, và getUpdates không chạy khi webhook được đặt. GọideleteWebhook, hoặc giữ webhook và ngừng polling.
Lỗi 413, 429 và 5xx
413 Request Entity Too Large: file upload lớn hơn mức API chấp nhận. Bot upload được tới 50 MB quaapi.telegram.org; local Bot API server nâng mức này lên 2000 MB.429 Too Many Requests: retry after N: flood control. Chờparameters.retry_aftergiây rồi gửi lại. Sau đó giảm tốc: khoảng 1 tin mỗi giây cho mỗi chat, 20 tin mỗi phút trong group, tổng cộng khoảng 30 tin mỗi giây. Con số cụ thể và cách dùng hàng đợi có trong bài về giới hạn.500,502 Bad Gatewayvà các lỗi 5xx khác: sự cố phía Telegram hoặc trên đường kết nối tới đó. Thử lại với exponential backoff. Body của lỗi 502 có thể là trang không phải JSON, nên đừng mặc địnhresponse.json()luôn thành công.
Code xử lý lỗi với retry_after và migrate_to_chat_id
Hàm bọc dưới đây thử lại lỗi 429 sau retry_after, đi theo migrate_to_chat_id, giãn thời gian chờ khi gặp 5xx và lỗi mạng, và ném lỗi có kiểu cho các trường hợp còn lại để nơi gọi tự quyết định. Bản Python dùng requests; bản JavaScript cần Node.js 18+ và chạy dưới dạng file .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):
# lỗi mạng hoặc phản hồi không phải JSON (ví dụ trang 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: chờ đúng thời gian yêu cầu
time.sleep(extra["retry_after"])
continue
if "migrate_to_chat_id" in extra and "chat_id" in params:
print(f"chat {params['chat_id']} đã chuyển sang {extra['migrate_to_chat_id']}: cập nhật database")
params["chat_id"] = extra["migrate_to_chat_id"]
continue
if code is not None and code >= 500: # sự cố phía Telegram: giãn thời gian chờ
time.sleep(2 ** attempt)
continue
raise TelegramError(method, code, data.get("description", ""), extra)
raise TelegramError(method, None, "bỏ cuộc sau nhiều lần thử")
def notify(chat_id, text):
try:
return call("sendMessage", chat_id=chat_id, text=text)
except TelegramError as e:
if e.code == 403:
# bị chặn, bị kick hoặc tài khoản đã xóa: ngừng nhắn vào chat này
print(f"không gửi được tới chat {chat_id}: {e.description}")
elif e.code == 400 and "chat not found" in e.description.lower():
print(f"sai chat id {chat_id}")
else:
raise
notify(123456789, "Xin chào!")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 {
// lỗi mạng hoặc phản hồi không phải JSON (ví dụ trang 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: chờ đúng thời gian yêu cầu
await sleep(extra.retry_after);
continue;
}
if (extra.migrate_to_chat_id !== undefined && "chat_id" in params) {
console.log(`chat ${params.chat_id} đã chuyển sang ${extra.migrate_to_chat_id}: cập nhật database`);
params.chat_id = extra.migrate_to_chat_id;
continue;
}
if (code >= 500) { // sự cố phía Telegram: giãn thời gian chờ
await sleep(2 ** attempt);
continue;
}
throw new TelegramError(method, code, data.description ?? "", extra);
}
throw new TelegramError(method, null, "bỏ cuộc sau nhiều lần thử");
}
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) {
// bị chặn, bị kick hoặc tài khoản đã xóa: ngừng nhắn vào chat này
console.log(`không gửi được tới chat ${chatId}: ${err.description}`);
} else if (err.code === 400 && err.description.toLowerCase().includes("chat not found")) {
console.log(`sai chat id ${chatId}`);
} else {
throw err;
}
}
}
await notify(123456789, "Xin chào!");Một lưu ý: request bị timeout phía bạn vẫn có thể đã được xử lý, nên thử gửi lại sau lỗi mạng đôi khi sẽ khiến tin nhắn đến hai lần.
Checklist debug
- Ghi log toàn bộ JSON của mọi phản hồi lỗi:
error_code,descriptionvàparameters. - Kiểm tra token bằng getMe trong Bot API Tester: 401 nghĩa là vấn đề nằm ở chính token.
- Với
chat not foundvà lỗi 403, gọigetUpdatesvà sochat.idthật với id trong cấu hình. - Với 409, tìm instance thứ hai đang chạy và kiểm tra
getWebhookInfo.
Bài liên quan: chat id Telegram lấy ở đâu, API gửi tin nhắn Telegram và escape parse_mode, giới hạn Telegram Bot API và xử lý lỗi 429 và cài webhook Telegram bot.
Câu hỏi thường gặp
Lỗi “Bad Request: chat not found” trong Telegram nghĩa là gì?
Bot không thấy chat ứng với chat_id bạn truyền: id sai hoặc thiếu tiền tố -100, người dùng chưa từng start bot, hoặc bot không phải thành viên của group hay kênh. Hãy nhắn cho bot trước rồi lấy id từ getUpdates.
Xử lý lỗi “Forbidden: bot was blocked by the user” thế nào?
Phía bot không sửa được: người dùng đã chặn bot. Hãy bắt mã lỗi 403, đánh dấu người dùng không còn hoạt động trong database và ngừng gửi cho họ cho tới khi họ nhắn lại cho bot.
Vì sao getUpdates trả về 409 Conflict?
Hoặc có tiến trình khác đang polling với cùng token (terminated by other getUpdates request), hoặc bot đang đặt webhook (can't use getUpdates method while webhook is active). Dừng instance thứ hai hoặc gọi deleteWebhook.
Sau lỗi 429 Too Many Requests cần chờ bao lâu?
Đúng bằng số giây trong parameters.retry_after, rồi gửi lại request. Đừng thử lại ngay và đừng viết cứng thời gian chờ: giá trị này thay đổi theo từng phản hồi.
Code có nên kiểm tra nội dung description của lỗi không?
Càng ít càng tốt. Description là chuỗi cho người đọc và Telegram có thể thay đổi. Hãy rẽ nhánh theo error_code và parameters trước, chỉ so khớp chuỗi con (không phân biệt hoa thường) trong description khi cần phân biệt hai lỗi cùng mã.
401 Unauthorized trong Bot API nghĩa là gì?
Token không hợp lệ: gõ sai, đã bị thu hồi trong @BotFather, hoặc thuộc môi trường khác (production và server test). Kiểm tra bằng getMe và lấy token hiện tại qua /mybots → API Token.
Bài viết liên quan
Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên
Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.
Cách deploy bot Telegram: VPS, Docker và hosting serverless
Cách deploy bot Telegram: chọn polling hay webhook, chạy service systemd trên VPS, Docker, Cloudflare Workers với secret_token và checklist lên production.
Telegram Bot API 10.0–10.5: cài đặt bot, widget, rich message, tin nhắn ephemeral, guest mode và hơn thế
Tổng hợp thay đổi Telegram Bot API 10.0–10.5: setMySettings, BotFullInfo, widget HTML, rich message, tin nhắn ephemeral, guest mode, kèm ví dụ JSON.
Giới hạn Telegram Bot API: rate limit, lỗi 429, dung lượng file và độ dài tin nhắn
Giới hạn Telegram Bot API: 30 tin/giây, 1 tin/giây mỗi chat, 20 tin/phút trong group, xử lý lỗi 429 retry_after, dung lượng file và độ dài tin nhắn.
Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start
Cài lệnh cho bot Telegram: /setcommands trong @BotFather, setMyCommands theo scope và ngôn ngữ, tham số deep link của /start và lệnh /cmd@bot trong nhóm.
Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard
Thêm nút bấm cho bot Telegram: inline keyboard với callback_data, answerCallbackQuery, sửa tin nhắn sau khi bấm, reply keyboard và ForceReply, có code mẫu.
Tích hợp n8n với Telegram: kết nối bot, kích hoạt workflow và gửi tin nhắn
Kết nối n8n với Telegram: dùng token bot làm Access Token, Telegram Trigger cần webhook HTTPS công khai, gửi tin nhắn theo chat id và cách sửa lỗi hay gặp.
API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript
Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.
Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ
Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.
Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n
Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.
Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic
Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.
Bot inline Telegram: cách bật inline mode và trả lời inline query
Hướng dẫn làm bot inline Telegram: bật inline mode qua @BotFather hoặc setMySettings, xử lý update inline_query và trả kết quả bằng answerInlineQuery.
Thanh toán Telegram Stars cho bot: hóa đơn, pre-checkout, hoàn tiền và thuê bao
Nhận thanh toán Telegram Stars trong bot: sendInvoice với XTR, pre_checkout_query, successful_payment, hoàn tiền, gói thuê bao và code Python/JS.
Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram
Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.
Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ
Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.
TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn
Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.
Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python
Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.
Widget Telegram: HTML tương tác ngay trong tin nhắn của bot
Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.
Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật
Hướng dẫn test Telegram Mini App: chạy mock trên trình duyệt, localhost qua tunnel HTTPS, môi trường test, DevTools từng nền tảng và xác thực initData.