Telegram Bot API

Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür

· 9 dk okuma

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"
}
AlanAnlamı
okBaşarısız her istekte false.
error_codeTam sayı, HTTP durumunu yansıtır: 400, 401, 403, 404, 409, 413, 429, 5xx.
descriptionDüz metin açıklama, genellikle durum adıyla başlar: Bad Request:, Forbidden:, Conflict:.
parametersHatayı 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:

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çıklamaNedenÇözüm
chat not foundYanlış 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_INVALIDId 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 modifiedDü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 foundYanlış 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 editedMesaj 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 emptytext 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 specifiedBaş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 invalidanswerCallbackQuery 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 chatNormal 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 inaccessibleBotun ü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

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çıklamaNe olduNe yapmalı
bot was blocked by the userKullanı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 userKullanı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 chatBot kanalda değil.Botu kanala gönderi yetkisi olan bir yönetici olarak ekleyin.
bot was kicked from the group chatBot 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 deactivatedHesap silinmiş.Kullanıcıyı gönderim listenizden silin.

getUpdates'te 409 Conflict

413, 429 ve 5xx hataları

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

  1. Başarısız her yanıtın JSON'unu eksiksiz loglayın: error_code, description ve parameters.
  2. Token'ı Bot API Tester'da getMe ile kontrol edin: 401, sorunun token'ın kendisi olduğunu gösterir.
  3. chat not found ve 403 hatalarında getUpdates çağırın ve gerçek chat.id'yi yapılandırmanızdakiyle karşılaştırın.
  4. 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.

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.