خطاهای 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 (آیدی جدید گروهی که به سوپرگروه تبدیل شده). |
دو پاسخ با 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 منتشر نمیکند. توضیحات این راهنما متنهایی هستند که API امروز برمیگرداند، اما متن ساده برای انساناند و ممکن است بدون اطلاع قبلی تغییر کنند. مستندات رسمی حتی میگوید محتوای error_code هم ممکن است تغییر کند. پس یک ربات مقاوم:
- اول بر اساس
error_code(400، 403، 429، 5xx) تصمیم میگیرد؛ - هر وقت
parameters.retry_afterوparameters.migrate_to_chat_idوجود دارند، به آنها تکیه میکند، نه به بیرون کشیدن عدد از description؛ - فقط وقتی باید خطاهای با کد یکسان را از هم جدا کند، بخشی از description را بدون حساسیت به حروف بزرگ و کوچک بررسی میکند و اگر چیزی پیدا نشد، رفتار پیشفرض امنی دارد؛
- description کامل را لاگ میکند تا پیامهای جدید در لاگها دیده شوند و گم نشوند.
خطای 400 Bad Request: خطاهای رایج تلگرام
خطای 400 Bad Request در تلگرام یعنی درخواست به API رسیده اما چیزی در آن اشکال دارد: یک پارامتر، چت مقصد یا وضعیت پیام.
| Description | علت | راه حل |
|---|---|---|
chat not found | chat_id اشتباه، آیدی گروه بدون -100، کاربری که هیچوقت ربات را استارت نکرده، رباتی که در گروه یا کانال نیست، یا آیدی production که روی سرور تست استفاده شده. | به ربات پیام بدهید (یا آن را به چت اضافه کنید) و آیدی را از getUpdates کپی کنید؛ راهنمای چت آیدی را ببینید. |
PEER_ID_INVALID | آیدی بدشکل است یا به چتی اشاره میکند که ربات هرگز با آن تعامل نداشته. | مثل chat not found: آیدی تازه را از یک آپدیت بگیرید. |
message is not modified | متد ویرایش با دقیقاً همان متن و reply markup فعلی پیام صدا زده شده. معمولاً وقتی کاربر یک دکمه را دو بار میزند. | قبل از ویرایش مقایسه کنید، یا این خطا را بگیرید و نادیده بگیرید. |
message to edit not found | جفت message_id/chat_id اشتباه است یا پیام حذف شده. | message_id برگشتی از متد ارسال را همراه با chat id آن ذخیره کنید. |
message can't be edited | پیام را ربات نفرستاده یا دیگر قابل ویرایش نیست. | به جای ویرایش، پیام جدید بفرستید. |
can't parse entities: … | مارکآپ parse_mode خراب است: < یا & بدون escape در HTML، یا یکی از _ * [ ] ( ) ~ ` > # + - = | { } . ! بدون escape در MarkdownV2. متن بعد از دونقطه offset بایتی را نشان میدهد. | متن ورودی کاربر را escape کنید یا آن را بدون parse_mode بفرستید. |
message text is empty | text وجود ندارد یا خالی است؛ اغلب بدنه JSON بدون Content-Type: application/json فرستاده شده. | مقدار و encoding درخواست را بررسی کنید. |
wrong file identifier/HTTP URL specified | file_id متعلق به ربات دیگر (file id به یک ربات گره خورده)، یا URLی که تلگرام نمیتواند دانلود کند یا از محدودیت ارسال با URL بیشتر است (5 MB برای عکس، 20 MB برای بقیه فایلها). | فایل را دوباره با multipart/form-data آپلود کنید یا از لینک مستقیم عمومی استفاده کنید. |
query is too old and response timeout expired or query ID is invalid | answerCallbackQuery یا answerInlineQuery خیلی دیر، دو بار یا با id اشتباه صدا زده شده. | همان اول handler و قبل از کارهای کند جواب بدهید؛ بعد از ریاستارت، callback queryهای قدیمی را رد کنید. |
not enough rights to send text messages to the chat (عکس، سند…) | ربات در گروه محدود شده یا در کانال دسترسی ارسال ندارد. | دسترسی لازم یا ادمینی را به ربات بدهید. |
group chat was upgraded to a supergroup chat | گروه معمولی به سوپرگروه تبدیل شده و آیدی جدید گرفته که در parameters.migrate_to_chat_id برمیگردد. | آیدی جدید را ذخیره کنید و درخواست را با آن تکرار کنید. |
BUTTON_DATA_INVALID و بقیه خطاهای reply markup | callback_data خارج از بازه 1 تا 64 بایت (هر حرف غیر لاتین، مثل حروف فارسی، 2 تا 4 بایت است) یا reply_markup بدشکل. | دادههای طولانی را روی سرور خود نگه دارید و فقط یک کلید کوتاه در callback_data بگذارید. |
member list is inaccessible | متدی مربوط به اعضا جایی صدا زده شده که ربات نمیتواند لیست اعضا را بخواند؛ معمولاً کانالی که ربات در آن ادمین نیست. | ربات را ادمین کنید یا آنجا اعضا را کوئری نکنید. |
برای بازتولید امن یک خطا، متد sendMessage را در Bot API Tester باز کنید، یک chat_id ساختگی وارد کنید و پاسخ خام JSON را ببینید.
خطای 401 Unauthorized و 404 Not Found
401 Unauthorized: توکن اشتباه است یا باطل شده. وقتی توکن production به سرور تست فرستاده شود (یا برعکس) هم پیش میآید. توکن را باgetMeبررسی کنید؛ اگر لو رفته و باطل شده، توکن جدید را از @BotFather بگیرید.404 Not Found: آدرس باhttps://api.telegram.org/bot<token>/METHOD_NAMEنمیخواند. علتهای رایج: نبود پیشوندbotقبل از توکن، فاصله یا شکست خط داخل توکن، یا اشتباه تایپی در نام متد. نام متدها به حروف بزرگ و کوچک حساس نیستند، پسsendmessageکار میکند ولیsendMesageنه.
خطای 403 Forbidden: bot was blocked by the user و خطاهای مشابه
خطای 403 یعنی ربات اجازه نوشتن در این چت را ندارد. تکرار درخواست فایدهای ندارد؛ به جایش دادههای خود را بهروز کنید.
| Description | چه اتفاقی افتاده | چه باید کرد |
|---|---|---|
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 | حساب کاربر حذف شده است. | کاربر را از لیست ارسال حذف کنید. |
خطای 409 Conflict در getUpdates
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running: دو پروسه با یک توکن polling میکنند؛ یک ترمینال فراموششده، کانتینر دوم یا دیپلویی که قبل از توقف نسخه قبلی شروع شده. برای هر توکن دقیقاً یک poller نگه دارید.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first: ربات وب هوک دارد و تا وقتی وب هوک تنظیم است getUpdates کار نمیکند.deleteWebhookرا صدا بزنید، یا وب هوک را نگه دارید و polling را متوقف کنید.
خطاهای 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: flood control. به اندازهparameters.retry_afterثانیه صبر کنید و تکرار کنید. بعد سرعت را کم کنید: حدود 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه و حدود 30 در ثانیه در مجموع. اعداد و روشهای صفبندی در راهنمای محدودیتها آمده است.500،502 Bad Gatewayو بقیه 5xx: مشکلی سمت تلگرام یا در مسیر رسیدن به آن. با exponential backoff دوباره امتحان کنید. بدنه پاسخ 502 ممکن است صفحهای غیر JSON باشد، پس فرض نکنیدresponse.json()همیشه موفق میشود.
کد مدیریت خطا با retry_after و migrate_to_chat_id
این wrapper خطای 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: # flood control با کد 429: همانقدر که گفته شده صبر کن
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: # مشکل سمت تلگرام: با تأخیر دوباره تلاش کن
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, "سلام!")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) { // flood control با کد 429: همانقدر که گفته شده صبر کن
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) { // مشکل سمت تلگرام: با تأخیر دوباره تلاش کن
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, "سلام!");یک نکته: درخواستی که سمت شما timeout شده ممکن است در تلگرام پردازش شده باشد؛ پس تکرار ارسال بعد از خطای شبکه گاهی یک پیام را دو بار تحویل میدهد.
چکلیست دیباگ
- JSON کامل هر پاسخ ناموفق را لاگ کنید:
error_code،descriptionوparameters. - توکن را با متد getMe در Bot API Tester بررسی کنید: 401 یعنی مشکل از خود توکن است.
- برای
chat not foundو خطاهای 403،getUpdatesرا صدا بزنید وchat.idواقعی را با مقدار تنظیمات خود مقایسه کنید. - برای 409، دنبال نمونه دوم در حال اجرا بگردید و
getWebhookInfoرا بررسی کنید.
راهنماهای مرتبط: چت آیدی تلگرام و روش پیدا کردن آن، ارسال پیام با ربات تلگرام و escape در parse_mode، محدودیتهای Telegram Bot API و مدیریت خطای 429 و آموزش وب هوک تلگرام.
پرسشهای متداول
خطای «Bad Request: chat not found» در تلگرام یعنی چه؟
ربات چتی را که پشت chat_id شماست نمیبیند: آیدی اشتباه است یا پیشوند -100 را ندارد، کاربر هیچوقت ربات را استارت نکرده، یا ربات عضو گروه یا کانال نیست. اول به ربات پیام بدهید و آیدی را از getUpdates بردارید.
با خطای «Forbidden: bot was blocked by the user» چه کنم؟
از سمت ربات قابل رفع نیست: کاربر ربات را بلاک کرده است. خطای 403 را بگیرید، کاربر را در دیتابیس غیرفعال علامت بزنید و تا وقتی دوباره به ربات پیام نداده، برایش چیزی نفرستید.
چرا getUpdates خطای 409 Conflict میدهد؟
یا پروسه دیگری با همان توکن polling میکند (terminated by other getUpdates request) یا وب هوک تنظیم شده است (can't use getUpdates method while webhook is active). نمونه دوم را متوقف کنید یا deleteWebhook را صدا بزنید.
بعد از خطای 429 Too Many Requests چقدر صبر کنم؟
دقیقاً به اندازه parameters.retry_after بر حسب ثانیه، بعد درخواست را تکرار کنید. فوراً دوباره امتحان نکنید و مقدار تأخیر را در کد ثابت نگذارید؛ این مقدار در هر پاسخ فرق میکند.
آیا کد باید متن description خطا را بررسی کند؟
تا جای ممکن نه. description یک رشته قابلخواندن برای انسان است که تلگرام ممکن است تغییرش دهد. اول بر اساس error_code و parameters تصمیم بگیرید و فقط وقتی باید دو خطا با کد یکسان را از هم جدا کنید، بخشی از description را بدون حساسیت به حروف بزرگ و کوچک بررسی کنید.
خطای 401 Unauthorized در Bot API یعنی چه؟
توکن نامعتبر است: اشتباه تایپ شده، در @BotFather باطل (revoke) شده یا مال محیط دیگر است (production در برابر سرور تست). آن را با getMe بررسی کنید و توکن فعلی را از /mybots → API Token بگیرید.
آموزشهای مرتبط
ساخت ربات تلگرام: آموزش قدمبهقدم از BotFather تا اولین پیام با Python
ساخت ربات تلگرام قدمبهقدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.
دیپلوی ربات تلگرام: راهاندازی روی VPS، داکر و هاست Serverless
آموزش دیپلوی و هاست ربات تلگرام: polling یا وب هوک، سرویس systemd روی VPS، داکر، Cloudflare Workers با secret_token و چکلیست راهاندازی.
Telegram Bot API 10.0 تا 10.5: تنظیمات ربات، ویجتها، پیامهای rich و ephemeral، حالت مهمان و بیشتر
تغییرات Telegram Bot API 10.0 تا 10.5: متد setMySettings و BotFullInfo، ویجتهای HTML، پیامهای rich و ephemeral و حالت مهمان، همراه با مثال JSON.
محدودیتهای Telegram Bot API: نرخ ارسال، خطای 429، حجم فایل و طول پیام
محدودیتهای Telegram Bot API به زبان ساده: 30 پیام در ثانیه، 1 پیام در ثانیه در هر چت، 20 در دقیقه در گروه، مدیریت خطای 429 و محدودیت حجم فایل.
دستورات ربات تلگرام: setMyCommands، اسکوپ دستورات و دیپلینک /start
تنظیم دستورات ربات تلگرام: /setcommands در @BotFather، متد setMyCommands با اسکوپ و زبان، پارامتر دیپلینک /start و دستور /cmd@bot در گروهها.
کیبورد ربات تلگرام: دکمه شیشهای (inline keyboard)، دکمههای callback و reply keyboard
ساخت دکمه شیشهای ربات تلگرام: inline keyboard با callback_data، پاسخ با answerCallbackQuery، ویرایش پیام بعد از کلیک، reply keyboard و ForceReply.
اتصال n8n به تلگرام: وصل کردن ربات، اجرای ورکفلو و ارسال پیام
اتصال n8n به تلگرام: توکن ربات به عنوان Access Token، وب هوک Telegram Trigger روی HTTPS عمومی، ارسال پیام با چت آیدی و رفع خطاهای رایج.
ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)
آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالببندی HTML و MarkdownV2، دکمه شیشهای و رفع خطاها.
توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم
توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.
وب هوک ربات تلگرام: راهاندازی setWebhook، بررسی و رفع خطا
آموزش ست وب هوک تلگرام با setWebhook: پیشنیازهای HTTPS و پورتها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.
چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم
چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدیهای منفی و رفع مشکل نتیجه خالی و خطای 409.
ربات اینلاین تلگرام: فعال کردن حالت inline و پاسخ به کوئریها
ساخت ربات اینلاین تلگرام: فعال کردن حالت inline با @BotFather یا setMySettings، دریافت آپدیت inline_query و پاسخ با answerInlineQuery.
پرداخت با Telegram Stars در ربات: فاکتور، پیشپرداخت، بازپرداخت و اشتراک
دریافت پرداخت با استارز تلگرام در ربات: sendInvoice با ارز XTR، پاسخ به pre_checkout_query، successful_payment، بازپرداخت و اشتراک با کد پایتون و JS.
سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم
سرور تست تلگرام برای رباتها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.
ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنتها و دکمه اشتراکگذاری
ورود با تلگرام در سایت با Telegram Login (OIDC) و ویجت قدیمی همراه کد بررسی hash، جاسازی پست کانال، ویجت کامنت و دکمه اشتراکگذاری تلگرام.
مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیتها
مرجع API جاوااسکریپت ویجت تلگرام: ویژگیها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیتها.
مثال ویجت تلگرام: کد کامل HTML و ربات پایتون
مثالهای کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیشنمایش در مرورگر با ربات پایتون.
ویجت تلگرام چیست؟ HTML تعاملی داخل پیامهای ربات
ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیتها، جاهایی که فعلاً کار میکند و تفاوت با مینی اپ.
تست مینی اپ تلگرام: از mock در مرورگر تا اجرای واقعی در تلگرام
تست مینی اپ تلگرام قدم به قدم: حالت mock در مرورگر، اجرای localhost با تونل HTTPS، محیط تست، DevTools در هر پلتفرم و اعتبارسنجی initData در سرور.