Telegram Bot API

Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục

· 9 phút đọ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
okfalse với mọi request thất bại.
error_codeSố nguyên, trùng với HTTP status: 400, 401, 403, 404, 409, 413, 429, 5xx.
descriptionGiải thích dạng văn bản, thường có tiền tố là tên status: Bad Request:, Forbidden:, Conflict:.
parametersResponseParameters 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ẽ:

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.

DescriptionNguyên nhânCách sửa
chat not foundSai 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_INVALIDId 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 modifiedGọ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 foundCặ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 editedTin 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 emptyThiế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 specifiedfile_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 invalidGọ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 chatGroup 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áccallback_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 inaccessibleGọ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

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.

DescriptionChuyện gì đã xảy raCần làm gì
bot was blocked by the userNgườ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 userNgườ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 chatBot 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 chatBot đã 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 deactivatedTài khoản đã bị xóa.Xóa người dùng khỏi danh sách gửi tin.

409 Conflict trong getUpdates

Lỗi 413, 429 và 5xx

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

  1. Ghi log toàn bộ JSON của mọi phản hồi lỗi: error_code, description và parameters.
  2. Kiểm tra token bằng getMe trong Bot API Tester: 401 nghĩa là vấn đề nằm ở chính token.
  3. Với chat not found và lỗi 403, gọi getUpdates và so chat.id thật với id trong cấu hình.
  4. 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.

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.