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 اشتباه، کاربری که ربات را بلاک کرده، نمونه دوم ربات یا ارسال بیش از حد پیام در ثانیه. در ادامه قالب پاسخ خطا، جدول رایج‌ترین خطاها با راه حل (دسته‌بندی‌شده بر اساس کد) و کد آماده 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:.
parametersResponseParameters اختیاری که به مدیریت خودکار خطا کمک می‌کند: 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 هم ممکن است تغییر کند. پس یک ربات مقاوم:

خطای 400 Bad Request: خطاهای رایج تلگرام

خطای 400 Bad Request در تلگرام یعنی درخواست به API رسیده اما چیزی در آن اشکال دارد: یک پارامتر، چت مقصد یا وضعیت پیام.

Descriptionعلتراه حل
chat not foundchat_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 emptytext وجود ندارد یا خالی است؛ اغلب بدنه JSON بدون Content-Type: application/json فرستاده شده.مقدار و encoding درخواست را بررسی کنید.
wrong file identifier/HTTP URL specifiedfile_id متعلق به ربات دیگر (file id به یک ربات گره خورده)، یا URLی که تلگرام نمی‌تواند دانلود کند یا از محدودیت ارسال با URL بیشتر است (5 MB برای عکس، 20 MB برای بقیه فایل‌ها).فایل را دوباره با multipart/form-data آپلود کنید یا از لینک مستقیم عمومی استفاده کنید.
query is too old and response timeout expired or query ID is invalidanswerCallbackQuery یا 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 markupcallback_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

خطای 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

خطاهای 413، 429 و 5xx

کد مدیریت خطا با 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 شده ممکن است در تلگرام پردازش شده باشد؛ پس تکرار ارسال بعد از خطای شبکه گاهی یک پیام را دو بار تحویل می‌دهد.

چک‌لیست دیباگ

  1. JSON کامل هر پاسخ ناموفق را لاگ کنید: error_code، description و parameters.
  2. توکن را با متد getMe در Bot API Tester بررسی کنید: 401 یعنی مشکل از خود توکن است.
  3. برای chat not found و خطاهای 403، getUpdates را صدا بزنید و chat.id واقعی را با مقدار تنظیمات خود مقایسه کنید.
  4. برای 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 در سرور.