Telegram Bot API 错误码大全:每种报错的含义与解决方法
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 的内容也可能变化。因此,健壮的机器人应该:
- 首先根据
error_code(400、403、429、5xx)分支处理; - 只要有
parameters.retry_after和parameters.migrate_to_chat_id就直接使用,而不是从描述中解析数字; - 只在需要区分同一错误码下的不同错误时才匹配描述子串,匹配时不区分大小写,并在都不匹配时有安全的兜底逻辑;
- 完整记录描述内容,这样新出现的错误信息会出现在日志里,而不是被悄悄吞掉。
400 Bad Request:Telegram 常见错误
Telegram 400 Bad Request 表示请求已经到达 API,但其中有问题:参数、目标聊天或消息状态不对。
| 描述 | 原因 | 解决方法 |
|---|---|---|
chat not found | chat_id 写错、群组 ID 缺少 -100、用户从未启动过机器人、机器人不在群组或频道中,或者在测试服务器上用了正式环境的 ID。 | 给机器人发消息(或把它加入聊天),从 getUpdates 中复制 ID,参见 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 与对应的 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
401 Unauthorized:Token 错误或已被撤销。把正式环境的 Token 发到测试服务器(或反过来)也会出现这个错误。用getMe检查 Token;如果 Token 泄露并已撤销,请从 @BotFather 获取新的。404 Not Found:URL 不符合https://api.telegram.org/bot<token>/METHOD_NAME格式。常见原因:Token 前漏了bot前缀、Token 中带有空格或换行,或者方法名拼错。方法名不区分大小写,所以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 | 用户从未打开过机器人。机器人不能主动发起对话。 | 请用户点击 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
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running:两个进程在用同一个 Token 轮询,比如忘关的终端、第二个容器,或者旧实例还没停新实例就启动了的部署。每个 Token 只保留一个轮询进程。Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first:机器人设置了 Webhook,此时 getUpdates 无法使用。调用deleteWebhook,或者保留 Webhook 并停止轮询。
413、429 和 5xx 错误
413 Request Entity Too Large:上传的文件超过 API 允许的大小。通过api.telegram.org机器人最多可上传 50 MB;本地 Bot API 服务器可以提高到 2000 MB。429 Too Many Requests: retry after N:触发了频率限制。等待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 频率限制:按要求等待
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 可能已经处理了,所以网络错误后重发消息偶尔会导致同一条消息发送两次。
排查清单
- 完整记录每个失败响应的 JSON:
error_code、description和parameters。 - 用 Bot API Tester 的 getMe 检查 Token:返回 401 说明问题出在 Token 本身。
- 遇到
chat not found和 403 错误时,调用getUpdates,把真实的chat.id与配置中的值对比。 - 遇到 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 校验代码。