Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür
Telegram Bot API hataları "ok": false, 400, 403 veya 429 gibi sayısal bir error_code ve Bad Request: chat not found gibi okunabilir bir description içeren JSON olarak döner. Çoğunun nedeni bilinen bir avuç durumdan biridir: yanlış chat id, botu engellemiş bir kullanıcı, ikinci bir bot örneği ya da saniyede çok fazla mesaj. Aşağıda yanıt formatını, koda göre gruplanmış en sık hatalar ve çözümleri tablosunu ve retry_after ile migrate_to_chat_id'yi dikkate alan, kopyalayıp kullanabileceğiniz Python ve JavaScript hata yönetimi kodunu bulacaksınız.
Hata yanıtının formatı
Her Bot API yanıtı, Boolean bir ok alanı olan bir JSON nesnesidir. Başarılı olursa veri result içindedir; başarısız olursa bunun yerine şunu alırsınız:
{
"ok": false,
"error_code": 400,
"description": "Bad Request: chat not found"
}
| Alan | Anlamı |
|---|---|
ok | Başarısız her istekte false. |
error_code | Tam sayı, HTTP durumunu yansıtır: 400, 401, 403, 404, 409, 413, 429, 5xx. |
description | Düz metin açıklama, genellikle durum adıyla başlar: Bad Request:, Forbidden:, Conflict:. |
parameters | Hatayı otomatik yönetmeye yardım eden isteğe bağlı ResponseParameters: retry_after (flood kontrolünden sonra beklenecek saniye) ve migrate_to_chat_id (süper gruba dönüşen grubun yeni id'si). |
Kodda yönetmeniz gereken, parameters içeren iki yanıt:
{"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}}
Mantığı açıklama metnine dayandırmayın
Telegram, Bot API hata mesajlarının tam listesini yayımlamaz. Bu rehberdeki açıklamalar API'nin bugün döndürdüğü metinlerdir; ancak insanlar için yazılmış düz metinlerdir ve haber verilmeden değişebilir. Resmi dokümantasyon error_code içeriğinin bile değişebileceğini söyler. Bu yüzden sağlam bir bot:
- önce
error_code'a göre dallanır (400, 403, 429, 5xx); - açıklamadan sayı ayıklamak yerine, varsa
parameters.retry_afterveparameters.migrate_to_chat_id'ye güvenir; - açıklamada alt metin aramayı yalnızca aynı koda sahip hataları ayırması gerektiğinde, büyük/küçük harf duyarsız ve hiçbir şey eşleşmezse güvenli bir varsayılanla yapar;
- açıklamanın tamamını loglar, böylece yeni mesajlar yutulmak yerine loglarınızda görünür.
400 Bad Request: sık görülen Telegram hataları
Telegram'da 400 Bad Request hatası, isteğin API'ye ulaştığını ama içinde bir şeyin yanlış olduğunu gösterir: bir parametre, hedef sohbet veya mesajın durumu.
| Açıklama | Neden | Çözüm |
|---|---|---|
chat not found | Yanlış chat_id, -100 öneki olmayan grup id'si, botu hiç başlatmamış kullanıcı, grupta veya kanalda olmayan bot ya da test sunucusunda kullanılan üretim id'si. | Bota mesaj yazın (veya botu sohbete ekleyin) ve id'yi getUpdates'ten kopyalayın; chat id rehberine bakın. |
PEER_ID_INVALID | Id bozuk veya botun hiç etkileşime girmediği bir sohbeti gösteriyor. | chat not found ile aynı: bir güncellemeden taze id alın. |
message is not modified | Düzenleme metodu, mesajda zaten olan metin ve reply markup ile birebir aynı değerlerle çağrıldı. Kullanıcı aynı butona iki kez bastığında tipiktir. | Düzenlemeden önce karşılaştırın ya da bu hatayı yakalayıp yok sayın. |
message to edit not found | Yanlış message_id/chat_id çifti veya mesaj silinmiş. | Gönderim metodunun döndürdüğü message_id'yi chat id'siyle birlikte saklayın. |
message can't be edited | Mesaj bot tarafından gönderilmemiş veya artık düzenlenemiyor. | Düzenlemek yerine yeni bir mesaj gönderin. |
can't parse entities: … | Bozuk parse_mode işaretlemesi: HTML'de kaçırılmamış bir < veya &, MarkdownV2'de ise kaçırılmamış _ * [ ] ( ) ~ ` > # + - = | { } . ! karakterlerinden biri. İki nokta üst üsteden sonraki metin bayt konumunu gösterir. | Kullanıcıdan gelen metni escape edin veya parse_mode olmadan gönderin. |
message text is empty | text eksik veya boş; çoğu zaman Content-Type: application/json olmadan gönderilmiş bir JSON gövdesi. | Değeri ve isteğin kodlamasını kontrol edin. |
wrong file identifier/HTTP URL specified | Başka bir bota ait file_id (file id'ler tek bir bota bağlıdır) ya da Telegram'ın indiremediği veya URL limitlerini (fotoğraflar için 5 MB, diğer dosyalar için 20 MB) aşan bir URL. | Dosyayı multipart/form-data ile yeniden yükleyin veya herkese açık doğrudan bir link kullanın. |
query is too old and response timeout expired or query ID is invalid | answerCallbackQuery veya answerInlineQuery çok geç, iki kez ya da yanlış id ile çağrıldı. | Yavaş işlerden önce, handler'ın en başında yanıt verin; yeniden başlatmadan sonra eski callback query'leri atlayın. |
not enough rights to send text messages to the chat (fotoğraf, doküman…) | Bot grupta kısıtlanmış veya kanalda gönderi yetkisi yok. | Bota gerekli izni veya yönetici yetkilerini verin. |
group chat was upgraded to a supergroup chat | Normal grup süper gruba dönüştü ve parameters.migrate_to_chat_id içinde dönen yeni bir id aldı. | Yeni id'yi kaydedin ve isteği onunla tekrarlayın. |
BUTTON_DATA_INVALID ve diğer reply markup hataları | 1–64 bayt dışında callback_data (Latin dışı karakterler ve ğ, ş gibi harfler 2–4 bayt tutar) veya bozuk bir reply_markup. | Uzun verileri sunucunuzda saklayın, callback_data'ya kısa bir anahtar koyun. |
member list is inaccessible | Botun üye listesini okuyamadığı bir yerde, genellikle yönetici olmadığı bir kanalda üyelerle ilgili bir metot çağrıldı. | Botu yönetici yapın veya orada üye sorgulamayın. |
Bir hatayı güvenle yeniden üretmek için Bot API Tester'da sendMessage'ı açın, uydurma bir chat_id girin ve ham JSON yanıtına bakın.
401 Unauthorized ve 404 Not Found
401 Unauthorized: token yanlış veya iptal edilmiş. Üretim token'ı test sunucusuna gönderildiğinde (ya da tersi) de olur. Token'ıgetMeile kontrol edin; sızdığı için iptal edildiyse yenisini @BotFather'dan alın.404 Not Found: URLhttps://api.telegram.org/bot<token>/METHOD_NAMEkalıbına uymuyor. Tipik nedenler: token'dan öncebotönekinin eksik olması, boşluk veya satır sonu içeren token ya da yanlış yazılmış metot adı. Metot adları büyük/küçük harfe duyarsızdır; yanisendmessageçalışır amasendMesageçalışmaz.
403 Forbidden: bot was blocked by the user ve benzeri hatalar
403 hatası, botun bu sohbete yazmasına izin verilmediği anlamına gelir. Tekrar denemek işe yaramaz; bunun yerine verilerinizi güncelleyin.
| Açıklama | Ne oldu | Ne yapmalı |
|---|---|---|
bot was blocked by the user | Kullanıcı botu engelledi veya durdurdu. | Kullanıcıyı pasif olarak işaretleyin ve mesaj göndermeyi bırakın. Özel sohbetlerde bot, engellendiğinde veya engeli kaldırıldığında bir my_chat_member güncellemesi de alır. |
bot can't initiate conversation with a user | Kullanıcı botu hiç açmamış. Botlar ilk mesajı yazamaz. | Kullanıcıdan Start'a basmasını isteyin, ör. bir t.me/your_bot linkiyle. |
bot is not a member of the channel chat | Bot kanalda değil. | Botu kanala gönderi yetkisi olan bir yönetici olarak ekleyin. |
bot was kicked from the group chat | Bot gruptan çıkarıldı (süper grup varyantında supergroup chat yazar). | Sohbeti listenizden çıkarın veya bir yöneticiden botu tekrar eklemesini isteyin. |
user is deactivated | Hesap silinmiş. | Kullanıcıyı gönderim listenizden silin. |
getUpdates'te 409 Conflict
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running— iki süreç aynı token'la polling yapıyor: unutulmuş bir terminal, ikinci bir container ya da eskisi durmadan başlayan bir deploy. Her token için yalnızca bir poller çalıştırın.Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first— botta webhook kurulu ve kuruluyken getUpdates çalışmaz.deleteWebhookçağırın ya da webhook'u koruyup polling'i durdurun.
413, 429 ve 5xx hataları
413 Request Entity Too Large: yükleme API'nin kabul ettiğinden büyük. Botlarapi.telegram.orgüzerinden 50 MB'a kadar yükleyebilir; yerel Bot API sunucusu bunu 2000 MB'a çıkarır.429 Too Many Requests: retry after N: flood kontrolü.parameters.retry_aftersaniye bekleyin ve tekrarlayın. Sonra yavaşlayın: sohbet başına saniyede yaklaşık 1 mesaj, grupta dakikada 20, toplamda saniyede yaklaşık 30. Sayılar ve kuyruk stratejileri limitler rehberinde.500,502 Bad Gatewayve diğer 5xx: Telegram tarafında veya yolda bir sorun. Üstel geri çekilmeyle (exponential backoff) tekrar deneyin. 502 gövdesi JSON olmayan bir sayfa olabilir;response.json()'ın her zaman başarılı olacağını varsaymayın.
retry_after ve migrate_to_chat_id ile hata yönetimi kodu
Bu sarmalayıcı 429'u retry_after sonrasında tekrar dener, migrate_to_chat_id'yi izler, 5xx ve ağ hatalarında geri çekilir ve geri kalan her şey için tipli bir hata fırlatır; kararı çağıran kod verir. Python requests kullanır; JavaScript sürümü Node.js 18+ gerektirir ve .mjs dosyası olarak çalışır.
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):
# ağ hatası veya JSON olmayan yanıt (ör. HTML 502 sayfası)
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 flood kontrolü: söylenen kadar bekle
time.sleep(extra["retry_after"])
continue
if "migrate_to_chat_id" in extra and "chat_id" in params:
print(f"sohbet {params['chat_id']} → {extra['migrate_to_chat_id']} taşındı: veritabanını güncelleyin")
params["chat_id"] = extra["migrate_to_chat_id"]
continue
if code is not None and code >= 500: # Telegram tarafında sorun: geri çekil
time.sleep(2 ** attempt)
continue
raise TelegramError(method, code, data.get("description", ""), extra)
raise TelegramError(method, None, "denemeler tükendi, vazgeçildi")
def notify(chat_id, text):
try:
return call("sendMessage", chat_id=chat_id, text=text)
except TelegramError as e:
if e.code == 403:
# engellendi, atıldı veya hesap silindi: bu sohbete yazmayı bırakın
print(f"sohbet {chat_id} erişilemez: {e.description}")
elif e.code == 400 and "chat not found" in e.description.lower():
print(f"yanlış chat id {chat_id}")
else:
raise
notify(123456789, "Merhaba!")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 {
// ağ hatası veya JSON olmayan yanıt (ör. HTML 502 sayfası)
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 flood kontrolü: söylenen kadar bekle
await sleep(extra.retry_after);
continue;
}
if (extra.migrate_to_chat_id !== undefined && "chat_id" in params) {
console.log(`sohbet ${params.chat_id} → ${extra.migrate_to_chat_id} taşındı: veritabanını güncelleyin`);
params.chat_id = extra.migrate_to_chat_id;
continue;
}
if (code >= 500) { // Telegram tarafında sorun: geri çekil
await sleep(2 ** attempt);
continue;
}
throw new TelegramError(method, code, data.description ?? "", extra);
}
throw new TelegramError(method, null, "denemeler tükendi, vazgeçildi");
}
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) {
// engellendi, atıldı veya hesap silindi: bu sohbete yazmayı bırakın
console.log(`sohbet ${chatId} erişilemez: ${err.description}`);
} else if (err.code === 400 && err.description.toLowerCase().includes("chat not found")) {
console.log(`yanlış chat id ${chatId}`);
} else {
throw err;
}
}
}
await notify(123456789, "Merhaba!");Bir uyarı: sizin tarafınızda zaman aşımına uğrayan bir istek yine de işlenmiş olabilir; bu yüzden ağ hatasından sonra gönderimi tekrar denemek nadiren mesajın iki kez iletilmesine yol açabilir.
Hata ayıklama kontrol listesi
- Başarısız her yanıtın JSON'unu eksiksiz loglayın:
error_code,descriptionveparameters. - Token'ı Bot API Tester'da getMe ile kontrol edin: 401, sorunun token'ın kendisi olduğunu gösterir.
chat not foundve 403 hatalarındagetUpdatesçağırın ve gerçekchat.id'yi yapılandırmanızdakiyle karşılaştırın.- 409'da çalışan ikinci bir örnek arayın ve
getWebhookInfo'yu kontrol edin.
İlgili rehberler: Telegram chat id nasıl bulunur, mesaj gönderme ve parse_mode'da escape, Telegram Bot API limitleri ve 429 yönetimi ve webhook kurulumu.
Sık sorulan sorular
Telegram'da “Bad Request: chat not found” ne demek?
Bot, chat_id'nin işaret ettiği sohbeti göremiyor: id yanlış ya da -100 öneki eksik, kullanıcı botu hiç başlatmamış veya bot grubun ya da kanalın üyesi değil. Önce bota mesaj yazın ve id'yi getUpdates'ten alın.
“Forbidden: bot was blocked by the user” hatası nasıl yönetilir?
Bot tarafında düzeltilemez: kullanıcı botu engellemiş. 403 hata kodunu yakalayın, kullanıcıyı veritabanında pasif olarak işaretleyin ve bota tekrar yazana kadar ona mesaj göndermeyi bırakın.
getUpdates neden 409 Conflict döndürüyor?
Ya aynı token'la başka bir süreç polling yapıyor (terminated by other getUpdates request) ya da webhook kurulu (can't use getUpdates method while webhook is active). İkinci örneği durdurun veya deleteWebhook çağırın.
429 Too Many Requests'ten sonra ne kadar beklemeliyim?
Tam olarak parameters.retry_after'ın söylediği kadar saniye, sonra isteği tekrarlayın. Hemen tekrar denemeyin ve beklemeyi sabit yazmayın: değer yanıttan yanıta değişir.
Kodum hata açıklamasının metnini kontrol etmeli mi?
Mümkün olduğunca az. Açıklama, Telegram'ın değiştirebileceği, insanlar için yazılmış bir metindir. Önce error_code ve parameters'a göre dallanın; açıklamada büyük/küçük harf duyarsız alt metin aramayı yalnızca aynı koda sahip iki hatayı ayırmanız gerektiğinde kullanın.
Bot API'de 401 Unauthorized ne anlama gelir?
Token geçersiz: yanlış yazılmış, @BotFather'da iptal edilmiş ya da diğer ortama (üretim veya test sunucusu) ait. getMe ile kontrol edin ve güncel token'ı /mybots → API Token'dan alın.
İlgili rehberler
Telegram bot nasıl yapılır? BotFather ile adım adım bot oluşturma
Telegram bot yapma rehberi: BotFather'da /newbot ile bot oluşturun, token'ı getMe ile test edin, chat ID'yi bulun ve Python ile ilk mesajı gönderin.
Telegram botu nasıl deploy edilir: VPS, Docker ve serverless hosting
Telegram botu sunucuya kurma: polling mi webhook mu, VPS'te systemd servisi, Docker, secret_token ile Cloudflare Workers ve yayın öncesi kontrol listesi.
Telegram Bot API 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası
Telegram Bot API 10.0–10.5'teki yenilikler: setMySettings ve BotFullInfo, HTML widget'lar, rich ve ephemeral mesajlar, misafir modu; JSON örnekleriyle.
Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu
Telegram Bot API limitleri: saniyede 30 mesaj, sohbet başına 1 mesaj/sn, grupta dakikada 20, 429 retry_after yönetimi, dosya boyutu ve mesaj uzunluğu.
Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link
Telegram bot komutları nasıl eklenir: @BotFather /setcommands, kapsam ve dil destekli setMyCommands, /start deep link parametresi, gruplarda /komut@bot.
Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye
Telegram bot butonu ekleme: callback_data ile inline klavye, answerCallbackQuery, basıştan sonra mesajı düzenleme, reply klavye ve ForceReply örnekleri.
n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme
n8n'i Telegram'a bağlayın: bot token'ı Access Token olarak girin, Telegram Trigger webhook'u için HTTPS kurun, chat id ile mesaj gönderin, hataları çözün.
Telegram Bot API ile mesaj gönderme (send message): curl, Python ve JavaScript
Telegram Bot API send message rehberi: curl, Python ve JavaScript ile sendMessage, HTML ve MarkdownV2 biçimlendirme, inline butonlar ve sık hatalar.
Telegram bot token nasıl alınır, nerede bulunur ve nasıl iptal edilir?
Telegram bot token nedir, BotFather'dan nasıl alınır, mevcut botun token'ı nerede bulunur? getMe ile test, 401 hatası ve sızan token'ı iptal etme.
Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme
Telegram bot webhook kurulumu: setWebhook ile HTTPS URL ve secret_token ayarlayın, getWebhookInfo ile hataları görün; 409 Conflict ve n8n localhost çözümü.
Telegram chat ID nasıl bulunur: kullanıcı, grup, kanal ve konu için adım adım
Telegram chat ID nasıl bulunur? getUpdates ile kullanıcı, grup, süper grup ve kanal ID'sini öğrenin; -100 ön eki, konu ID'si ve boş result sorunu.
Telegram inline bot: inline modu açma ve inline sorguları yanıtlama
Telegram inline bot nasıl yapılır: inline modu @BotFather veya setMySettings ile açın, inline_query güncellemelerini answerInlineQuery ile yanıtlayın.
Telegram botlarında Stars ile ödeme: fatura, ön onay, iade ve abonelikler
Telegram botunuzda Stars ile ödeme alın: XTR ile sendInvoice, pre_checkout_query, successful_payment, iade ve abonelikler; Python ve JS kodu.
Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?
Telegram test sunucusu nedir? Test ortamına giriş, test botu oluşturma, Bot API'yi /test/ ile çağırma ve Bot API Tester'da TEST modu adım adım.
Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu
Sitenize Telegram ile giriş ekleyin: yeni Telegram Login (OIDC), eski Login Widget ve hash kontrolü, gönderi gömme, yorumlar ve paylaş butonu.
TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar
Telegram widget API başvurusu: TelegramWidget özellikleri, request(), olaylar, hata kodları, CSS değişkenleri, widget_query, answerWidgetQuery ve sınırlar.
Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu
Çalışan Telegram widget örnekleri: statik sipariş kartı, widget_query ile sayaç, paylaşılan canlı anket ve yerel önizleme; HTML ve Python bot kodu.
Telegram widget: bot mesajının içinde çalışan etkileşimli HTML
Telegram widget nedir: Bot API 10.4'teki sendWidget, chat_data ve public_data nasıl çalışır, bugün nerede kullanılabilir, Mini App'ten farkı nedir?
Telegram Mini App nasıl test edilir: tarayıcıdaki mock'tan gerçek Telegram'a
Telegram Mini App test rehberi: tarayıcıda mock mod, HTTPS tünelle localhost, test ortamı, platformlara göre DevTools ve sunucuda initData doğrulama.