Error Telegram Bot API: Arti Setiap Error dan Cara Mengatasinya
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"
}
| Field | Arti |
|---|---|
ok | false untuk setiap request yang gagal. |
error_code | Integer, sama dengan status HTTP: 400, 401, 403, 404, 409, 413, 429, 5xx. |
description | Penjelasan teks biasa, umumnya diawali nama status: Bad Request:, Forbidden:, Conflict:. |
parameters | Objek 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:
- bercabang berdasarkan
error_codeterlebih dulu (400, 403, 429, 5xx); - mengandalkan
parameters.retry_afterdanparameters.migrate_to_chat_idjika ada, bukan mengambil angka dari description; - mencocokkan substring description hanya jika harus membedakan error dengan kode yang sama, tanpa membedakan huruf besar-kecil, dan dengan fallback aman jika tidak ada yang cocok;
- mencatat description lengkap di log, supaya pesan baru terlihat dan tidak tertelan begitu saja.
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.
| Description | Penyebab | Solusi |
|---|---|---|
chat not found | chat_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_INVALID | Format ID salah atau menunjuk chat yang belum pernah berinteraksi dengan bot. | Sama seperti chat not found: ambil ID baru dari update. |
message is not modified | Metode 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 found | Pasangan message_id/chat_id salah, atau pesan sudah dihapus. | Simpan message_id yang dikembalikan metode kirim bersama chat id-nya. |
message can't be edited | Pesan 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 empty | text tidak ada atau kosong, sering karena body JSON dikirim tanpa Content-Type: application/json. | Cek nilainya dan encoding request. |
wrong file identifier/HTTP URL specified | file_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 invalid | answerCallbackQuery 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 chat | Grup 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 lainnya | callback_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 inaccessible | Metode 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
401 Unauthorized: token salah atau sudah di-revoke. Bisa juga terjadi jika token produksi dikirim ke server tes atau sebaliknya. Cek token dengangetMe; jika token bocor dan sudah di-revoke, ambil token baru dari @BotFather.404 Not Found: URL tidak sesuai formathttps://api.telegram.org/bot<token>/METHOD_NAME. Penyebab umum: awalanbotsebelum token tidak ada, token mengandung spasi atau baris baru, atau nama metode salah ketik. Nama metode tidak case-sensitive, jadisendmessageberfungsi, tapisendMesagetidak.
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.
| Description | Yang terjadi | Yang harus dilakukan |
|---|---|---|
bot was blocked by the user | Pengguna 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 user | Pengguna 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 chat | Bot tidak ada di channel. | Tambahkan bot ke channel sebagai administrator dengan hak posting. |
bot was kicked from the group chat | Bot dikeluarkan dari grup (varian untuk supergrup menyebut supergroup chat). | Hapus chat dari daftar kamu atau minta admin menambahkan bot lagi. |
user is deactivated | Akun sudah dihapus. | Hapus pengguna dari daftar pengiriman. |
409 Conflict di getUpdates
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running— dua proses melakukan polling dengan token yang sama: terminal yang lupa ditutup, container kedua, atau deploy yang sudah jalan sebelum versi lama berhenti. Pastikan hanya ada satu poller per token.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first— bot punya webhook, dan getUpdates tidak berfungsi selama webhook terpasang. PanggildeleteWebhook, atau tetap pakai webhook dan hentikan polling.
Error 413, 429, dan 5xx
413 Request Entity Too Large: file yang diunggah lebih besar dari yang diterima API. Bot bisa mengunggah hingga 50 MB lewatapi.telegram.org; local Bot API server menaikkannya menjadi 2000 MB.429 Too Many Requests: retry after N: flood control. Tungguparameters.retry_afterdetik lalu ulangi. Setelah itu kurangi kecepatan: sekitar 1 pesan per detik per chat, 20 per menit di grup, sekitar 30 per detik secara total. Angka dan strategi antrean ada di panduan limit.500,502 Bad Gateway, dan 5xx lainnya: masalah di sisi Telegram atau di jalur menuju ke sana. Ulangi dengan exponential backoff. Body respons 502 bisa berupa halaman non-JSON, jadi jangan berasumsiresponse.json()selalu berhasil.
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
- Catat JSON lengkap setiap respons gagal:
error_code,description, danparameters. - Cek token dengan getMe di Bot API Tester: 401 berarti masalahnya ada di token.
- Untuk
chat not founddan error 403, panggilgetUpdatesdan bandingkanchat.idasli dengan yang ada di konfigurasi. - 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.
Panduan terkait
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.