Sık hatalar

Bot yazarken ya da çalıştırırken karşılaştığın belirtilerin büyük bölümü aynı birkaç nedenden çıkar. Önce aşağıdaki özet tabloya bak, ardından ilgili başlıktaki adımları uygula.

Hızlı teşhis tablosu

Bot çevrimdışı görünüyor

Bir botun sunucu üye listesinde yeşil (çevrimiçi) görünmesi yalnızca aktif bir gateway WebSocket oturumu açıkken olur:

1. Terminal penceren açıksa programın çalışmaya devam ettiğini ve READY olayını aldığını doğrula.

2. Yalnızca curl ya da fetch ile mesaj gönderen bir betik botu çevrimiçi göstermez; mesaj yine gider ama durum çevrimdışı kalır.

3. Bilgisayarını kapattığında bot çevrimdışı düşüyorsa süreci bir sunucuya taşı; adımlar Botu açık tut sayfasında.

message.content boş geliyor

Hata mesajı almadığın halde d.content === "" ve d.attachments === [] görüyorsan bu bir arıza değil, mesaj içeriği kuralıdır:

• MESSAGE_CONTENT ayrıcalıklı intent'i olmadan bot yalnızca kendi yazdığı ve kendisini doğrudan etiketleyen (@bot) mesajların metnini görür.

• Çözüm: Geliştirici portalında uygulamanı aç → Ayrıcalıklı intent'ler altında Mesaj içeriği'ni etkinleştir → kodunda Intents.MESSAGE_CONTENT (1 << 15) bitini ekle → programını yeniden başlat (açık oturum yeni intent'i kendiliğinden almaz).

Gateway 4014 veya 4004 ile kapanıyor

Bu iki kapanış kodunda yeniden bağlanmayı deneme; kodu ya da portal ayarını düzeltmeden her deneme aynı hatayla biter:

• 4014 DISALLOWED_INTENTS: Kodunda GUILD_MEMBERS (1 << 1), GUILD_PRESENCES (1 << 8) veya MESSAGE_CONTENT (1 << 15) istedin ama portalda o kutu kapalı; ya da botun 100+ sunucuda ve o intent henüz doğrulama sırasında onaylanmadı.

• 4004 AUTHENTICATION_FAILED: Token yanlış, başında/sonunda görünmez boşluk var, portalda yenilenmiş ya da uygulama durdurulmuş. Ayrıca yanlışlıkla kişilere ait /gateway adresine bağlanırsan da 4004 alırsın; adresi her zaman GET /api/v1/gateway/bot rotasından al.

HTTP 401 ve üç farklı 403 hatası

• 401 unauthorized: REST isteğinde Authorization: Bot <token> başlığı eksik ya da Bot sözcüğü unutulmuş (Bearer değil, bot rotalarında Bot yazılır).

• 403 missing_access: Botun o kanalı görme (ViewChannel, 1024) izni yok. Kanal özel bir kanalsa kanal izinlerinden botun rolüne ViewChannel ekle.

• 403 missing_permissions: Bot kanalı görüyor ama yapmak istediği işin izni (SendMessages, ManageMessages, ManageRoles gibi) rolünde yok ya da bot zaman aşımında.

• 403 role_hierarchy: İzin var ama botun rütbesi yetmiyor. Yeni eklenen botun rolü @everyone rolünün hemen üstünde başlar; sunucu yöneticisi Sunucu ayarları → Roller ekranında botun rolünü hedef üyenin veya verilecek rolün üstüne sürüklemelidir. Ayrıntılar İzinler sayfasında.

HTTP 429 hız sınırı ve geçici engel

429 aldığında yanıt gövdesindeki retry_after saniye kadar beklemeden aynı isteği tekrarlama. X-RateLimit-Scope: shared geliyorsa tüm platformun ortak bot tavanı dolmuştur; X-RateLimit-Scope: user veya bot geliyorsa kendi kotan dolmuştur.

Reddedilen (401, 403, 429) istekleri saniyede yüzlerce kez tekrarlayan bozuk bir döngü 10 dakikada 10.000 hataya ulaşırsa IP adresin geçici olarak 403 temporarily_banned alır. Resmi JavaScript ve Python kütüphaneleri bucket kuyruğunu ve 429 beklemelerini senin yerine otomatik yönetir.

Eğik çizgi (/) komutu görünmüyor

1. Komutu kaydettiğinden emin ol (await bot.commands.sync([...]) veya PUT /applications/{id}/commands).

2. İstemciler komut listesini en çok 60 saniyede bir yeniler; kaydettikten sonra bir dakika bekle ya da başka kanala geçip dön.

3. Kişinin o kanalda Uygulama komutlarını kullan (UseApplicationCommands) izni kapalıysa ya da komutun default_member_permissions bitleri kişide yoksa komut o kişiye gizlenir.

4. Botla açılan DM'de deniyorsan komutun global olduğundan, contexts içinde 1 bulunduğundan ve default_member_permissions değerinin null olduğundan emin ol; bkz. Komutlar.

Buton ya da komut "Bot yanıt vermedi." diyor

N'oluyo her INTERACTION_CREATE olayına 3 saniye içinde ilk yanıtın (POST /interactions/{id}/{token}/callback) gelmesini bekler:

• Yanıttan önce veritabanı sorgusu, dış API isteği ya da çoklu REST çağrısı yapıyorsan süre dolar ve 400 interaction_timeout alırsın.

• Çözüm: İşleyici başlar başlamaz await i.defer({ ephemeral: true }) (ham API'de type: 5 veya bileşende type: 6) gönder; 3 saniyelik süreyi 15 dakikaya uzatmış olursun, işin bitince await i.editReply(...) ile sonucu yaz. Ayrıntılar Etkileşimler sayfasında.

• HTTP ile teslim kullanıyorsan portalda Teslim günlüğü tablosuna bak: imza doğrulaması (401) ya da TLS hatası orada açıkça yazar.

Ses kanalına girmiyor ya da ses çıkmıyor

1. Ses kanalına girmek için POST /channels/{id}/voice çağırma (403 bot_forbidden döner); açık gateway bağlantından op 4 gönder veya SDK'da bot.voice.join(...) kullan.

2. VOICE_JOIN_ERROR olayı geliyorsa code alanını oku: missing_permissions ise ses kanalında ViewChannel, Connect ve Speak (izin=3146752) izinlerini ver; channel_bot_limit ise kanalda zaten 2 bot vardır.

3. Bot odaya giriyor ama ses gelmiyorsa sunucunda ffmpeg -version komutunun çalıştığını, sesin 48 kHz 2 kanal s16le PCM olarak çözüldüğünü ve TrackSource.SOURCE_MICROPHONE ile yayınlandığını doğrula. Ayrıntılar Ses sayfasında.

Bu sayfayı yapay zekaya verirsen

Sırada ne var

• Hatalar: API'deki tüm makinece okunur hata kodlarının tam referans tablosu

• SSS: izinler, mesajlar, DM kuralları ve ephemeral mesajlar hakkında sık sorulan sorular

• İzinler: izin bitleri ve rol hiyerarşisi hesaplaması