Discord "Etkileşim Başarısız Oldu" Hatası: 3 Saniye Kuralı ve Kesin Çözüm

3 saniye kuralı ve 15 dakikalık token

Kullanıcı bir komut, buton, select menu ya da modal kullandığında botunuza bir interaction gelir. Bu interaction'ın içinde bir token bulunur. Resmî belgedeki kural şudur:

Yani elinizde iki ayrı süre var: ilk yanıt için 3 saniye, ilk yanıttan sonra düzenleme ve takip mesajları için 15 dakika. Kullanıcının gördüğü "başarısız oldu" uyarısı, 3 saniyelik pencerenin hiçbir yanıt olmadan kapandığı anlamına gelir.

İlk yanıt türleri

Discord'a "interaction'ı aldım" demenin (acknowledge, kısaca ACK) birkaç yolu vardır. Resmî "Interaction Callback Type" tablosundaki türler ve discord.js karşılıkları:

Bunlardan biri 3 saniye içinde gönderildiği sürece uyarı çıkmaz. Sonrasında aynı token ile editReply() ve followUp() kullanabilirsiniz.

Hatanın en sık sebepleri

• Yavaş iş, erken yanıt yok: Komut önce veritabanı sorgusu, harici API çağrısı ya da dosya işlemi yapıyor, yanıtı en sonda veriyor. Toplam süre 3 saniyeyi geçince token ölüyor.
• Kod hiç yanıt vermiyor: Bir if dalı return ile çıkıyor, ya da kod yanıt satırına gelmeden hata fırlatıyor. Butonlar için hiç dinleyici yazılmamış olması da aynı sonucu verir.
• Botun aynı token ile iki kopyası çalışıyor: Örneğin hem bilgisayarınızda hem sunucuda. JDA wiki'nin sorun giderme sayfası bunu "Unknown interaction" hatasının iki sebebinden biri olarak sayıyor: interaction'ı diğer süreç yanıtlamıştır. Çözüm, fazladan süreçleri durdurmak ya da token'ı yenilemektir.
• Interactions Endpoint URL ayarlı: Belgeye göre interaction'ı gateway üzerinden ya da HTTP webhook ile alabilirsiniz ve bu iki yöntem birbirini dışlar. Developer Portal'da bir "Interactions Endpoint URL" girilmişse gateway botunuza interaction gelmez.
• Bot kapalı ya da yeniden başlıyor: Bot çevrimdışıyken gönderilen komutlara kimse yanıt veremez. Botu 7/24 açık tutmak için Discord bot 7/24 aktif tutma yazısına bakın.
• Olayları işleyen iş parçacığı tıkanıyor: JDA wiki, WebSocket iş parçacığının uzun süre bloklanmasını "did not respond" uyarısının sebeplerinden biri olarak gösteriyor. Node.js'te de senkron ağır bir işlem olay döngüsünü bekletir; yanıt kodunuz doğru olsa bile geç çalışır.

Çözüm 1: deferReply ile zaman kazanın

İşiniz 3 saniyeden uzun sürebilecekse ilk iş olarak deferReply() çağırın. Kullanıcı "<uygulama> düşünüyor..." benzeri bir yükleniyor durumu görür ve siz 15 dakika içinde sonucu editReply() ile yazarsınız.

const { Events, MessageFlags } = require('discord.js');

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand() || interaction.commandName !== 'rapor') return;

  // 1) Önce ACK: 3 saniye kuralını burada karşılıyoruz
  await interaction.deferReply({ flags: MessageFlags.Ephemeral });

  // 2) Uzun süren iş (en fazla 15 dakika)
  const veri = await raporuHazirla(interaction.guildId);

  // 3) Yükleniyor mesajını sonuçla değiştir
  await interaction.editReply(`Rapor hazır: ${veri.ozet}`);
});

• deferReply() çağrısını mümkün olan en erken yere koyun; öncesinde await ile beklenen hiçbir iş olmasın.
• Yanıtın gizli (ephemeral) olmasını istiyorsanız bayrağı defer anında verin. Bir mesajın ephemeral durumu sonradan değiştirilemez.
• Belgeye göre defer yanıtında geçerli tek mesaj bayrağı EPHEMERAL'dır. Components V2 ile mesaj göndermek istiyorsanız IS_COMPONENTS_V2 bayrağını editReply() sırasında verirsiniz. Ayrıntı: Components V2 nedir.
• Butonlar ve select menüler için, mesajı yerinde güncelleyecekseniz deferUpdate() kullanın; kullanıcı yükleniyor durumu görmez.

Çözüm 2: editReply ve followUp farkını bilin

discord.js rehberine göre deferReply() sonrasında ilk followUp(), yeni mesaj göndermek yerine yükleniyor mesajını düzenler. Resmî belge de bu davranışın geriye uyumluluk için korunduğunu ama kullanımdan kaldırıldığını belirtiyor; defer sonrası sonucu yazmak için editReply() kullanın.

Kullanıcıya yüklenen (user-install) ve sunucuya kurulu olmayan uygulamalarda takip mesajı sayısı interaction başına 5 ile sınırlıdır; sınır aşılırsa 40094 kodlu hata döner.

Konsoldaki hata kodları: 10062 ve 40060

Kullanıcı tarafındaki uyarının bot tarafındaki karşılığı genellikle bir DiscordAPIError'dır. Resmî JSON hata kodu tablosundaki ilgili kayıtlar:

discord.js ayrıca API'ye gitmeden önce kendi kontrolünü yapar ve InteractionAlreadyReplied ya da InteractionNotReplied gibi hata kodları fırlatır. Bunlar sırasıyla "zaten yanıt verdin" ve "önce ilk yanıtı vermelisin" anlamına gelir. Durumu kontrol etmek için interaction.replied ve interaction.deferred alanlarını kullanabilirsiniz.

const { RESTJSONErrorCodes, MessageFlags } = require('discord.js');

async function guvenliYanit(interaction, icerik) {
  try {
    if (interaction.deferred || interaction.replied) {
      return await interaction.followUp({ content: icerik, flags: MessageFlags.Ephemeral });
    }
    return await interaction.reply({ content: icerik, flags: MessageFlags.Ephemeral });
  } catch (hata) {
    if (hata.code === RESTJSONErrorCodes.UnknownInteraction) {
      console.warn('Interaction süresi dolmuş (10062), yanıt atlanıyor');
      return;
    }
    throw hata;
  }
}

discord.py'de aynı mantık

discord.py 2.x'te ilk yanıt interaction.response üzerinden verilir. InteractionResponse.defer() ertelenmiş yanıtı gönderir, interaction.followup.send() ise takip mesajı yollar.

@client.tree.command()
async def rapor(interaction: discord.Interaction):
    """Uzun süren rapor"""
    await interaction.response.defer()          # 3 saniye kuralını karşıla
    veri = await raporu_hazirla(interaction.guild_id)
    await interaction.followup.send(f'Rapor hazır: {veri}')

discord.py ile bot kurulumunun tamamı için discord.py ile bot yapımı yazısına bakabilirsiniz.

HTTP interactions kullanıyorsanız

Botunuz interaction'ları gateway yerine bir "Interactions Endpoint URL" ile alıyorsa, ilk yanıtı gelen HTTP isteğine doğrudan 200 durum kodu ve bir interaction response nesnesiyle de verebilirsiniz. 3 saniye kuralı burada da geçerlidir: işiniz uzun sürecekse önce tür 5 (deferred) yanıtı döndürün, sonucu ardından "Edit Original Interaction Response" uç noktasıyla (PATCH /webhooks/<application_id>/<interaction_token>/messages/@original) yazın. Kurulum için HTTP interactions ve Cloudflare Workers rehberine bakın.

Hızlı kontrol listesi

• Komut veritabanı ya da harici API bekliyorsa ilk satırda deferReply() var mı?
• Butonlar ve menüler için kalıcı bir interactionCreate dinleyicisi ya da aktif bir collector var mı?
• Aynı token ile çalışan ikinci bir süreç (eski terminal, PM2, Docker kopyası) var mı?
• Developer Portal'da istemeden girilmiş bir "Interactions Endpoint URL" var mı?
• Her kod dalında bir yanıt veriliyor mu, hata durumunda catch içinde yanıt veriliyor mu?
• Aynı interaction'a iki kez reply() çağrılıyor mu?

Süreç yönetimi için PM2 ile Node.js production ve systemd servis dosyası yazıları, tek bir bot kopyası çalıştırmanızı kolaylaştırır.

Sık Sorulan Sorular

"Etkileşim başarısız oldu" uyarısı botun çöktüğü anlamına mı gelir?

Hayır. Yalnızca bu interaction'a 3 saniye içinde ilk yanıt verilmediğini gösterir. Bot çalışıyor olabilir ama kod yanıt satırına geç ulaşmış, hiç ulaşmamış ya da interaction başka bir süreç tarafından alınmış olabilir.

deferReply sonrası ne kadar sürem var?

Interaction token'ı 15 dakika geçerlidir. Bu süre içinde editReply() ve followUp() kullanabilirsiniz. Daha uzun işler için sonucu interaction yerine normal bir kanal mesajıyla gönderin.

Butona bastığımda uyarı çıkıyor ama mesaj güncelleniyor, neden?

Mesajı başka bir yolla (örneğin message.edit()) düzenleyip interaction'ı hiç yanıtlamıyorsanız Discord yine de uyarıyı gösterir. Bileşen interaction'larında update() ya da deferUpdate() kullanın; bu ikisi interaction'ı yanıtlanmış sayar.

Unknown interaction hatasını yakalayıp yok saymak doğru mu?

Kayıt tutmak için yakalamak doğrudur, ama asıl çözüm yanıtı hızlandırmaktır. Hata sık tekrarlanıyorsa defer çağrısının yerini ve yinelenen bot süreçlerini kontrol edin.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Slash komut oluşturma · Buton, select menu ve modal · Discord API hata kodları · Rate limit ve 429 hatası · HTTP interactions · Botu 7/24 açık tutma