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 不对、用户屏蔽了机器人、同时运行了两个机器人实例,或者每秒发送的消息太多。下面依次介绍错误响应格式、按错误码分组的常见错误及解决方法表,以及可以直接复制使用、支持 retry_after 和 migrate_to_chat_id 的 Python 和 JavaScript 错误处理代码。

错误响应格式

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(触发频率限制后需要等待的秒数)和 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}}

不要依赖描述文本写业务逻辑

Telegram 并没有公开完整的 Bot API 错误信息列表。本文中的描述是 API 目前返回的文本,但它们是写给人看的纯文本,可能在没有通知的情况下改变。官方文档甚至说明 error_code 的内容也可能变化。因此,健壮的机器人应该:

400 Bad Request:Telegram 常见错误

Telegram 400 Bad Request 表示请求已经到达 API,但其中有问题:参数、目标聊天或消息状态不对。

描述原因解决方法
chat not foundchat_id 写错、群组 ID 缺少 -100、用户从未启动过机器人、机器人不在群组或频道中,或者在测试服务器上用了正式环境的 ID。给机器人发消息(或把它加入聊天),从 getUpdates 中复制 ID,参见 chat id 教程。
PEER_ID_INVALIDID 格式错误,或指向机器人从未交互过的聊天。与 chat not found 相同:从更新中重新获取 ID。
message is not modified调用编辑方法时,文本和回复键盘与消息现有内容完全相同。用户连续两次点击同一个按钮时很常见。编辑前先比较,或者捕获并忽略该错误。
message to edit not foundmessage_id 与 chat_id 不匹配,或者消息已被删除。把发送方法返回的 message_id 与对应的 chat 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 下载、超出了通过 URL 发送的限制(照片 5 MB,其他文件 20 MB)。以 multipart/form-data 重新上传文件,或使用公开的直链。
query is too old and response timeout expired or query ID is invalid调用 answerCallbackQuery 或 answerInlineQuery 太晚、重复调用或 ID 错误。在处理函数一开始、执行耗时操作之前就应答;重启后跳过过期的回调查询。
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 及其他回复键盘错误callback_data 超出 1–64 字节(非拉丁字符每个占 2–4 字节,中文一般占 3 字节),或者 reply_markup 格式错误。把较长的数据存在服务器上,callback_data 中只放一个短键。
member list is inaccessible在机器人无法读取成员列表的地方调用了成员相关的方法,通常是机器人不是管理员的频道。把机器人设为管理员,或者不要在那里查询成员。

想安全地复现错误,可以打开 Bot API Tester 的 sendMessage,随便填一个 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用户从未打开过机器人。机器人不能主动发起对话。请用户点击 Start,例如通过 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该账号已被删除。把该用户从推送列表中删除。

getUpdates 中的 409 Conflict

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 频率限制:按要求等待
            time.sleep(extra["retry_after"])
            continue
        if "migrate_to_chat_id" in extra and "chat_id" in params:
            print(f"聊天 {params['chat_id']} 已迁移到 {extra['migrate_to_chat_id']}:请更新数据库")
            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, "多次重试后放弃")


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_id} 无法送达:{e.description}")
        elif e.code == 400 and "chat not found" in e.description.lower():
            print(f"chat id 错误:{chat_id}")
        else:
            raise


notify(123456789, "你好!")
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 频率限制:按要求等待
      await sleep(extra.retry_after);
      continue;
    }
    if (extra.migrate_to_chat_id !== undefined && "chat_id" in params) {
      console.log(`聊天 ${params.chat_id} 已迁移到 ${extra.migrate_to_chat_id}:请更新数据库`);
      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, "多次重试后放弃");
}

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(`聊天 ${chatId} 无法送达:${err.description}`);
    } else if (err.code === 400 && err.description.toLowerCase().includes("chat not found")) {
      console.log(`chat id 错误:${chatId}`);
    } else {
      throw err;
    }
  }
}

await notify(123456789, "你好!");

需要注意:在你这一侧超时的请求,Telegram 可能已经处理了,所以网络错误后重发消息偶尔会导致同一条消息发送两次。

排查清单

  1. 完整记录每个失败响应的 JSON:error_code、description 和 parameters。
  2. 用 Bot API Tester 的 getMe 检查 Token:返回 401 说明问题出在 Token 本身。
  3. 遇到 chat not found 和 403 错误时,调用 getUpdates,把真实的 chat.id 与配置中的值对比。
  4. 遇到 409 时,检查是否有第二个正在运行的实例,并查看 getWebhookInfo。

相关教程:Telegram chat id 获取教程、发送消息与 parse_mode 转义、Telegram Bot API 限制与 429 处理,以及 Webhook 设置教程。

常见问题

Telegram 报错“Bad Request: chat not found”是什么意思?

机器人看不到 chat_id 对应的聊天:ID 写错了或缺少 -100 前缀,用户从未启动过机器人,或者机器人不是该群组或频道的成员。先给机器人发一条消息,再从 getUpdates 中获取 ID。

如何处理“Forbidden: bot was blocked by the user”?

机器人这一侧无法解决:用户屏蔽了机器人。捕获错误码 403,在数据库中把该用户标记为不活跃,并停止向其发送消息,直到用户再次给机器人发消息。

getUpdates 为什么返回 409 Conflict?

要么有另一个进程在用同一个 Token 轮询(terminated by other getUpdates request),要么设置了 Webhook(can't use getUpdates method while webhook is active)。停掉第二个实例,或者调用 deleteWebhook。

收到 429 Too Many Requests 后要等多久?

按 parameters.retry_after 给出的秒数等待,然后重新发送请求。不要立即重试,也不要把等待时间写死:每次响应的值都可能不同。

代码需要判断错误描述文本吗?

尽量少用。description 是给人看的字符串,Telegram 可能随时修改。应优先根据 error_code 和 parameters 分支处理,只有在需要区分同一错误码下的不同错误时,才对描述做不区分大小写的子串匹配。

Bot API 返回 401 Unauthorized 是什么意思?

Token 无效:输错了、已在 @BotFather 中撤销,或者属于另一个环境(正式环境与测试服务器)。用 getMe 检查,并通过 /mybots → API Token 获取当前的 Token。

Telegram 机器人教程:从零创建 Telegram 机器人并发送第一条消息

Telegram 机器人教程:在 @BotFather 中用 /newbot 创建机器人并获取 Token,用 getMe 验证,再通过 getUpdates 找到 chat_id,用 curl 和 Python 发出第一条消息,附常见问题排查。

Telegram 机器人部署教程:VPS、Docker 与 Serverless 托管方案

Telegram 机器人部署与托管指南:轮询还是 Webhook,VPS 上的 systemd 服务、Docker 部署、带 secret_token 校验的 Cloudflare Workers,以及上线检查清单。

Telegram Bot API 10.0–10.5 新功能:机器人设置、小组件、富文本消息、临时消息、访客模式等

Telegram Bot API 10.0–10.5 更新了什么:setMySettings 与 BotFullInfo、HTML 小组件、富文本消息、临时消息、访客模式,附 JSON 示例与升级清单。

Telegram Bot API 限制汇总:发送频率、429 错误、文件大小与消息长度

Telegram Bot API 频率限制详解:每秒约 30 条、单聊每秒 1 条、群组每分钟 20 条,429 错误与 retry_after 处理代码,以及文件大小和消息长度限制。

Telegram 机器人命令:setMyCommands、命令作用域与 /start 深层链接

Telegram 机器人命令配置教程:@BotFather /setcommands、按作用域和语言调用 setMyCommands、/start 深层链接参数,以及群组中的 /cmd@bot 用法。

Telegram 机器人键盘教程:内联键盘、回调按钮与回复键盘

Telegram 机器人按钮教程:用 callback_data 创建内联键盘、answerCallbackQuery 应答、点击后编辑消息,以及回复键盘和 ForceReply,附完整 Python 与 JS 示例。

n8n Telegram 集成教程:连接机器人、触发工作流并发送消息

n8n 对接 Telegram 机器人:把 bot token 填入 Access Token,Telegram Trigger 通过公网 HTTPS Webhook 接收消息,按 chat id 发送消息,以及常见报错的解决方法。

Telegram Bot API 发送消息教程:sendMessage 参数、格式、按钮与错误处理

Telegram Bot API 发送消息中文教程:sendMessage 参数说明,curl、Python、JavaScript 示例,HTML 与 MarkdownV2 格式、内联按钮、群组和频道发送,以及 400、403、429 错误处理。

Telegram Bot Token 怎么获取:获取、查看、验证和撤销机器人 Token

Telegram Bot Token 怎么获取?用 @BotFather 的 /newbot 获取新 Token,在 /mybots 中查看已有 Token,用 getMe 检查是否有效,泄露后及时撤销,并配合 chat_id 接入 n8n 等工具。

Telegram Bot Webhook 设置教程:用 setWebhook 配置 Webhook URL 和 secret_token

Telegram Bot API setWebhook 中文教程:Webhook URL 的 HTTPS 与端口要求、secret_token 请求头校验、用 getWebhookInfo 排错、用 deleteWebhook 切回轮询,以及 409 等常见错误的解决方法。

Telegram chat id 获取教程:查看用户、群组、频道和话题的聊天 ID

Telegram chat id 获取教程:用 getUpdates 查看私聊、群组、超级群组、频道和论坛话题的聊天 ID,讲清负数和 -100 前缀的含义,并排查 result 为空、409 Conflict 等常见问题,附 Python 示例。

Telegram 内联机器人教程:开启 Inline 模式并用 answerInlineQuery 响应查询

Telegram 内联机器人(inline bot)开发教程:用 @BotFather 或 setMySettings 开启 Inline 模式,处理 inline_query 更新,并通过 answerInlineQuery 返回结果。

Telegram 机器人 Stars 支付教程:发票、预结账确认、退款与订阅

Telegram 机器人接入 Stars 支付:用 XTR 调用 sendInvoice,处理 pre_checkout_query 和 successful_payment,退款与订阅,附 Python/JS 代码。

Telegram 测试服务器:如何在 Telegram 测试环境中测试机器人

Telegram 测试服务器中文教程:如何登录测试环境、创建测试机器人、通过 /test/ 调用 Bot API,以及在 Bot API Tester 中开启 TEST 开关测试 Telegram 机器人。

Telegram 网站小部件教程:用 Telegram 登录网站、嵌入帖子、评论区与分享按钮

在网站上接入 Telegram:新版 Telegram 登录(OpenID Connect)、旧版 Login Widget 及 hash 校验代码、嵌入 Telegram 帖子、评论区小部件和分享按钮,附常见问题排查。

TelegramWidget JavaScript API:属性、事件、错误码与限制参考

TelegramWidget JavaScript API 中文参考:属性、request()、事件、错误码、CSS 变量,widget_query 与 answerWidgetQuery 的用法,以及小组件的全部限制。

Telegram Widget 示例:完整的小组件 HTML 与 Python 机器人代码

可直接运行的 Telegram widget 示例:静态订单卡片、用 widget_query 通信的计数器、共享小组件实时投票,以及本地预览与体积检查脚本,附完整 Python 代码。

Telegram 小组件(Widget)入门:在机器人消息中运行交互式 HTML

Telegram 小组件(Bot API 10.4)是什么:sendWidget 怎么发送、chat_data 与 public_data 状态如何运作、目前在哪里可用,以及与 Mini App 的区别。

Telegram Mini App 测试教程:从浏览器模拟到真实 Telegram 客户端

Telegram Mini App 测试全流程:浏览器模拟模式、通过 HTTPS 隧道在 localhost 调试、测试环境、各平台打开 DevTools 的方法,以及服务器端 initData 校验代码。