Telegram Bot API

Error Telegram Bot API: Arti Setiap Error dan Cara Mengatasinya

· 9 menit baca

Error Telegram Bot API dikembalikan sebagai JSON dengan "ok": false, error_code berupa angka seperti 400, 403, atau 429, dan description yang bisa dibaca manusia, misalnya Bad Request: chat not found. Sebagian besar punya salah satu dari belasan penyebab yang sudah dikenal: chat id salah, pengguna memblokir bot, ada instance bot kedua, atau terlalu banyak pesan per detik. Di bawah ini ada format respons, tabel error paling umum beserta solusinya per kode, dan kode penanganan siap pakai dalam Python dan JavaScript yang menghormati retry_after dan migrate_to_chat_id.

Format respons error

Setiap respons Bot API adalah objek JSON dengan field Boolean ok. Jika berhasil, datanya ada di result; jika gagal, kamu mendapat ini:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}
FieldArti
okfalse untuk setiap request yang gagal.
error_codeInteger, sama dengan status HTTP: 400, 401, 403, 404, 409, 413, 429, 5xx.
descriptionPenjelasan teks biasa, umumnya diawali nama status: Bad Request:, Forbidden:, Conflict:.
parametersObjek ResponseParameters opsional untuk menangani error secara otomatis: retry_after (detik yang harus ditunggu setelah flood control) dan migrate_to_chat_id (ID baru grup yang berubah menjadi supergrup).

Dua respons dengan parameters yang sebaiknya ditangani di kode:

{"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}}

Jangan bangun logika di atas teks description

Telegram tidak menerbitkan daftar lengkap pesan error Bot API. Description di panduan ini adalah teks yang dikembalikan API saat ini, tapi itu teks biasa untuk manusia dan bisa berubah tanpa pemberitahuan. Dokumentasi resmi bahkan menyebut isi error_code bisa berubah. Karena itu, bot yang andal:

400 Bad Request: error Telegram yang paling umum

Error 400 Bad Request di Telegram berarti request sampai ke API, tapi ada yang salah di dalamnya: parameter, chat tujuan, atau status pesan.

DescriptionPenyebabSolusi
chat not foundchat_id salah, ID grup tanpa -100, pengguna belum pernah memulai bot, bot tidak ada di grup atau channel, atau ID produksi dipakai di server tes.Kirim pesan ke bot (atau tambahkan bot ke chat) dan salin ID dari getUpdates; lihat panduan chat id.
PEER_ID_INVALIDFormat ID salah atau menunjuk chat yang belum pernah berinteraksi dengan bot.Sama seperti chat not found: ambil ID baru dari update.
message is not modifiedMetode edit dipanggil dengan teks dan reply markup yang persis sama dengan yang sudah ada. Sering terjadi saat pengguna menekan tombol yang sama dua kali.Bandingkan sebelum mengedit, atau tangkap dan abaikan error ini.
message to edit not foundPasangan message_id/chat_id salah, atau pesan sudah dihapus.Simpan message_id yang dikembalikan metode kirim bersama chat id-nya.
message can't be editedPesan tidak dikirim oleh bot, atau sudah tidak bisa diedit.Kirim pesan baru, jangan mengedit.
can't parse entities: …Markup parse_mode rusak: < atau & tidak di-escape di HTML, atau salah satu dari _ * [ ] ( ) ~ ` > # + - = | { } . ! tidak di-escape di MarkdownV2. Teks setelah titik dua menunjukkan offset byte.Escape teks dari pengguna, atau kirim tanpa parse_mode.
message text is emptytext tidak ada atau kosong, sering karena body JSON dikirim tanpa Content-Type: application/json.Cek nilainya dan encoding request.
wrong file identifier/HTTP URL specifiedfile_id dari bot lain (file id terikat pada satu bot), atau URL yang tidak bisa diunduh Telegram atau melebihi limit kirim lewat URL (5 MB untuk foto, 20 MB untuk file lain).Unggah ulang file sebagai multipart/form-data, atau pakai link langsung yang publik.
query is too old and response timeout expired or query ID is invalidanswerCallbackQuery atau answerInlineQuery dipanggil terlambat, dua kali, atau dengan ID yang salah.Jawab di awal handler, sebelum proses lambat; setelah restart, lewati callback query yang sudah basi.
not enough rights to send text messages to the chat (foto, dokumen…)Bot dibatasi di grup atau tidak punya hak posting di channel.Beri bot izin yang dibutuhkan atau hak admin.
group chat was upgraded to a supergroup chatGrup biasa berubah menjadi supergrup dan mendapat ID baru, yang dikembalikan di parameters.migrate_to_chat_id.Simpan ID baru dan ulangi request dengannya.
BUTTON_DATA_INVALID dan error reply markup lainnyacallback_data di luar 1–64 byte (karakter non-Latin memakan 2–4 byte), atau reply_markup yang formatnya salah.Simpan payload panjang di server dan taruh key pendek di callback_data.
member list is inaccessibleMetode terkait anggota dipanggil di tempat bot tidak bisa membaca daftar anggota, biasanya channel tempat bot bukan administrator.Jadikan bot administrator, atau jangan query anggota di sana.

Untuk mereproduksi error dengan aman, buka sendMessage di Bot API Tester, masukkan chat_id asal-asalan, dan lihat jawaban JSON mentahnya.

401 Unauthorized dan 404 Not Found

403 Forbidden: bot was blocked by the user dan error serupa

Error 403 berarti bot tidak diizinkan menulis ke chat ini. Mengulang request tidak akan membantu; perbarui data kamu.

DescriptionYang terjadiYang harus dilakukan
bot was blocked by the userPengguna memblokir atau menghentikan bot.Tandai pengguna tidak aktif dan berhenti mengirim pesan. Di chat pribadi, bot juga menerima update my_chat_member saat diblokir atau dibuka blokirnya.
bot can't initiate conversation with a userPengguna belum pernah membuka bot. Bot tidak bisa menulis duluan.Minta pengguna menekan Start, misalnya lewat link t.me/your_bot.
bot is not a member of the channel chatBot tidak ada di channel.Tambahkan bot ke channel sebagai administrator dengan hak posting.
bot was kicked from the group chatBot dikeluarkan dari grup (varian untuk supergrup menyebut supergroup chat).Hapus chat dari daftar kamu atau minta admin menambahkan bot lagi.
user is deactivatedAkun sudah dihapus.Hapus pengguna dari daftar pengiriman.

409 Conflict di getUpdates

Error 413, 429, dan 5xx

Kode penanganan error dengan retry_after dan migrate_to_chat_id

Wrapper ini mengulang 429 setelah retry_after, mengikuti migrate_to_chat_id, melakukan backoff saat 5xx dan error jaringan, dan melempar error bertipe untuk kasus lainnya agar pemanggil bisa memutuskan. Versi Python memakai requests; versi JavaScript butuh Node.js 18+ dan dijalankan sebagai 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):
            # error jaringan atau jawaban non-JSON (misalnya halaman 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: tunggu sesuai instruksi
            time.sleep(extra["retry_after"])
            continue
        if "migrate_to_chat_id" in extra and "chat_id" in params:
            print(f"chat {params['chat_id']} pindah ke {extra['migrate_to_chat_id']}: perbarui database")
            params["chat_id"] = extra["migrate_to_chat_id"]
            continue
        if code is not None and code >= 500:  # masalah di sisi Telegram: backoff
            time.sleep(2 ** attempt)
            continue
        raise TelegramError(method, code, data.get("description", ""), extra)
    raise TelegramError(method, None, "menyerah setelah beberapa percobaan")


def notify(chat_id, text):
    try:
        return call("sendMessage", chat_id=chat_id, text=text)
    except TelegramError as e:
        if e.code == 403:
            # diblokir, dikeluarkan, atau akun nonaktif: berhenti kirim ke chat ini
            print(f"chat {chat_id} tidak bisa dijangkau: {e.description}")
        elif e.code == 400 and "chat not found" in e.description.lower():
            print(f"chat id salah: {chat_id}")
        else:
            raise


notify(123456789, "Halo!")
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 {
      // error jaringan atau jawaban non-JSON (misalnya halaman 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: tunggu sesuai instruksi
      await sleep(extra.retry_after);
      continue;
    }
    if (extra.migrate_to_chat_id !== undefined && "chat_id" in params) {
      console.log(`chat ${params.chat_id} pindah ke ${extra.migrate_to_chat_id}: perbarui database`);
      params.chat_id = extra.migrate_to_chat_id;
      continue;
    }
    if (code >= 500) { // masalah di sisi Telegram: backoff
      await sleep(2 ** attempt);
      continue;
    }
    throw new TelegramError(method, code, data.description ?? "", extra);
  }
  throw new TelegramError(method, null, "menyerah setelah beberapa percobaan");
}

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) {
      // diblokir, dikeluarkan, atau akun nonaktif: berhenti kirim ke chat ini
      console.log(`chat ${chatId} tidak bisa dijangkau: ${err.description}`);
    } else if (err.code === 400 && err.description.toLowerCase().includes("chat not found")) {
      console.log(`chat id salah: ${chatId}`);
    } else {
      throw err;
    }
  }
}

await notify(123456789, "Halo!");

Satu catatan: request yang timeout di sisi kamu mungkin tetap diproses, jadi mengulang pengiriman setelah error jaringan sesekali bisa membuat pesan terkirim dua kali.

Checklist debugging

  1. Catat JSON lengkap setiap respons gagal: error_code, description, dan parameters.
  2. Cek token dengan getMe di Bot API Tester: 401 berarti masalahnya ada di token.
  3. Untuk chat not found dan error 403, panggil getUpdates dan bandingkan chat.id asli dengan yang ada di konfigurasi.
  4. Untuk 409, cari instance kedua yang masih berjalan dan cek getWebhookInfo.

Panduan terkait: cara mendapatkan chat id Telegram, kirim pesan dan escaping parse_mode, limit Telegram Bot API dan penanganan 429, serta setting webhook.

Pertanyaan umum

Apa arti “Bad Request: chat not found” di Telegram?

Bot tidak bisa melihat chat dengan chat_id tersebut: ID-nya salah atau tanpa awalan -100, pengguna belum pernah memulai bot, atau bot bukan anggota grup atau channel itu. Kirim pesan ke bot dulu dan ambil ID dari getUpdates.

Bagaimana menangani “Forbidden: bot was blocked by the user”?

Error ini tidak bisa diperbaiki dari sisi bot: pengguna memblokir bot. Tangkap kode 403, tandai pengguna sebagai tidak aktif di database, dan berhenti mengirim pesan sampai ia menulis ke bot lagi.

Kenapa getUpdates mengembalikan 409 Conflict?

Ada proses lain yang melakukan polling dengan token yang sama (terminated by other getUpdates request), atau webhook sedang terpasang (can't use getUpdates method while webhook is active). Hentikan instance kedua atau panggil deleteWebhook.

Berapa lama harus menunggu setelah 429 Too Many Requests?

Persis selama nilai parameters.retry_after, dalam detik, lalu ulangi request. Jangan langsung mengulang dan jangan hardcode jeda: nilainya berubah dari respons ke respons.

Apakah kode saya perlu mengecek teks description error?

Sesedikit mungkin. Description adalah teks untuk manusia yang bisa diubah Telegram. Bercabanglah berdasarkan error_code dan parameters dulu, dan cek substring description (tanpa membedakan huruf besar-kecil) hanya jika perlu membedakan dua error dengan kode yang sama.

Apa arti 401 Unauthorized di Bot API?

Token tidak valid: salah ketik, sudah di-revoke di @BotFather, atau milik lingkungan lain (produksi vs server tes). Cek dengan getMe dan ambil token terbaru lewat /mybots → API Token.

Cara Membuat Bot Telegram: dari BotFather sampai Pesan Pertama

Cara membuat bot telegram langkah demi langkah: daftar di @BotFather, simpan token, cek dengan getMe, lalu kirim pesan pertama lewat curl dan Python.

Cara Deploy Bot Telegram: Hosting di VPS, Docker, dan Serverless

Cara deploy bot Telegram: polling vs webhook, service systemd di VPS, Docker, Cloudflare Workers dengan secret_token, plus checklist sebelum bot online.

Telegram Bot API 10.0–10.5: Pengaturan Bot, Widget, Rich Message, Ephemeral Message, Guest Mode, dan Lainnya

Fitur baru Telegram Bot API 10.0–10.5: setMySettings dan BotFullInfo, widget HTML, rich message, ephemeral message, guest mode, lengkap dengan contoh JSON.

Limit Telegram Bot API: Rate Limit, Error 429, Ukuran File, dan Panjang Pesan

Limit Telegram Bot API: 30 pesan/detik, 1 pesan/detik per chat, 20/menit di grup, cara menangani 429 retry_after, batas ukuran file dan panjang pesan.

Perintah Bot Telegram: setMyCommands, Scope Perintah, dan Deep Link /start

Cara membuat perintah bot Telegram: /setcommands di @BotFather, setMyCommands dengan scope dan bahasa, parameter deep link /start, dan /cmd@bot di grup.

Keyboard Bot Telegram: Inline Keyboard, Tombol Callback, dan Reply Keyboard

Cara membuat tombol bot Telegram: inline keyboard dengan callback_data, answerCallbackQuery, edit pesan setelah tombol ditekan, reply keyboard, ForceReply.

Integrasi n8n Telegram: Hubungkan Bot, Jalankan Workflow, dan Kirim Pesan

Cara menghubungkan n8n ke Telegram: token bot sebagai Access Token, webhook Telegram Trigger via HTTPS publik, kirim pesan via chat id, dan solusi error.

Kirim Pesan Bot Telegram dengan Telegram Bot API (sendMessage)

Kirim pesan bot telegram lewat Bot API: contoh sendMessage dengan curl, Python, dan JavaScript, format HTML/MarkdownV2, tombol inline, dan solusi error.

Telegram Bot Token: Cara Mendapatkan, Mengecek, dan Mencabut Token

Cara mendapatkan token bot telegram dari @BotFather, melihat token bot lama, mengecek dengan getMe, dan me-revoke token yang bocor. Lengkap dengan contoh.

Webhook Telegram Bot: Cara Setting setWebhook, Secret Token, dan Mengatasi Error

Panduan webhook telegram bot: syarat HTTPS dan port, setWebhook dengan secret_token, cek getWebhookInfo, deleteWebhook, serta solusi error 409 dan n8n.

Chat ID Telegram Dimana? Cara Mendapatkan Chat ID User, Grup, dan Channel

Chat id telegram dimana? Cara mendapatkan chat id user, grup, supergroup, dan channel lewat getUpdates, plus solusi saat result kosong atau error 409.

Bot Inline Telegram: Cara Mengaktifkan Mode Inline dan Menjawab Inline Query

Cara membuat bot inline Telegram: aktifkan mode inline lewat @BotFather atau setMySettings, tangani update inline_query, lalu balas via answerInlineQuery.

Pembayaran Telegram Stars untuk Bot: Invoice, Pre-Checkout, Refund, dan Langganan

Cara menerima pembayaran Telegram Stars di bot: sendInvoice dengan XTR, pre_checkout_query, successful_payment, refund, langganan, plus kode Python/JS.

Server Test Telegram: Cara Test Bot di Lingkungan Test Telegram

Cara memakai server test Telegram untuk bot: login ke lingkungan test, buat bot test, panggil Bot API lewat /test/, lalu aktifkan TEST di tester kami.

Widget Telegram untuk Website: Login dengan Telegram, Embed Post, Komentar, dan Tombol Share

Pasang widget telegram untuk website: login dengan Telegram (OIDC), Login Widget lama dengan cek hash, embed post, komentar channel, dan tombol share.

API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan

Referensi API JavaScript TelegramWidget: properti, request(), event, kode error, variabel CSS, widget_query dan answerWidgetQuery, plus semua batasannya.

Contoh Widget Telegram: Kode HTML dan Bot Python Lengkap

Contoh widget telegram lengkap dengan kode: kartu pesanan statis, counter dengan request widget_query, polling live sebagai widget shared, preview lokal.

Widget Telegram: HTML Interaktif di Dalam Pesan Bot

Widget telegram (Bot API 10.4): apa itu, cara kerja sendWidget, chat_data dan public_data, di mana bisa dipakai saat ini, dan bedanya dengan Mini App.

Cara Tes Telegram Mini App: Dari Mock di Browser sampai Telegram Asli

Cara tes Telegram Mini App: mode mock di browser, localhost lewat tunnel HTTPS, test environment, DevTools per platform, dan validasi initData di server.