Discord API Hata Kodları Rehberi: Gateway, HTTP ve JSON Hata Kodları

Discord hataları üç katmanda gelir

• Gateway kapanış kodları: botunuzun WebSocket bağlantısı kapandığında gelir. Örneğin 4004 token hatası, 4014 izin verilmeyen intent.
• HTTP durum kodları: REST isteğinin genel sonucudur. 403, 404, 429 gibi.
• JSON hata kodları: HTTP koduna ek olarak gövdedeki code alanında gelen ayrıntılı koddur. Örneğin 403 ile birlikte 50013 (izin eksik).

Bir REST hatası şöyle görünür. message alanı okunabilir açıklamayı, code alanı ise programla kontrol edebileceğiniz numarayı verir. Bazı hatalarda alan bazlı ayrıntıları içeren bir errors nesnesi de bulunur:

{
  "message": "Invalid authentication token",
  "code": 50014
}

Gateway kapanış kodları (4000-4014)

Discord, bozuk yeniden bağlanma döngülerini önlemek için bazı kapanış kodlarını "tekrar bağlanmayı durdur" sinyali olarak görmenizi ister. Aşağıdaki tablonun son sütunu bunu gösterir.

En sık görülenler 4004, 4014 ve 4011'dir. 4004 genellikle token'ın yanlış kopyalanmasından ya da sıfırlandıktan sonra güncellenmemesinden kaynaklanır; discord.js rehberi ayrıca client secret'ın token sanılarak kullanılmasını yaygın bir neden olarak sayar. Bkz. bot token nedir ve nasıl korunur. 4013 ve 4014 için Discord intent rehberi, 4010 ve 4011 için Discord sharding yazılarına bakın.

HTTP durum kodları

En sık karşılaşılan JSON hata kodları

Resmî tabloda yüzlerce kod var; aşağıda bot geliştiricilerin en sık gördüklerini seçtik. "Anlamı" sütunu belgedeki açıklamanın çevirisidir, "Çözüm" sütunu ise kontrol etmeniz gereken yerleri özetler.

Sık görülen hataların açıklaması ve çözümü

50013 Missing Permissions

Botun yapmak istediği işlem için gereken izin yok. En yaygın senaryolar: rol vermeye çalışırken botun en yüksek rolünün hedef rolün altında kalması, kanal bazlı izin üzerine yazmalarının (permission overwrite) botu kısıtlaması ya da davet linkinde gereken iznin verilmemiş olması. İşlemden önce izni kodda kontrol etmek, 403 üretip geçersiz istek sayınızı artırmaktan iyidir. Rol hiyerarşisi için Discord bot izinleri ve rol hiyerarşisi, davet linki için botu sunucuya ekleme yazısına bakın.

50001 Missing Access

Belgedeki açıklama yalnızca "Missing access" olsa da pratikte bot ilgili kanalı veya kaynağı göremediğinde karşılaşılır. Kanalın izinlerinde botun ya da rolünün kanalı görüntüleme iznini kontrol edin; botun o sunucuda hâlâ bulunduğundan emin olun.

10062 Unknown Interaction

Discord'a göre bir etkileşime ilk yanıtı 3 saniye içinde göndermelisiniz; süre aşılırsa token geçersizleşir ve sonraki yanıt 10062 ile döner. Uzun süren işlerde önce deferReply() ile etkileşimi onaylayın; token 15 dakika geçerlidir. Aynı etkileşime iki kez ilk yanıt vermeye çalışırsanız 40060 alırsınız. Bu iki hata kullanıcıya "Etkileşim başarısız oldu" olarak yansır; ayrıntılı çözüm için "Etkileşim başarısız oldu" hatası rehberine bakın.

50007 Cannot send messages to this user

discord.js rehberi bu hatanın nedenlerini şöyle sıralar: bot ile kullanıcının ortak sunucusu yoktur (çoğunlukla kullanıcıyı attıktan veya yasakladıktan sonra DM atmaya çalışılır), bot başka bir bota DM atmaya çalışır, kullanıcı botu engellemiştir ya da gizlilik ayarlarında DM'leri kapatmıştır. Son iki durum önceden kontrol edilemez; DM gönderimini mutlaka hata yakalama ile sarın. Moderasyon botlarında DM'i cezadan önce göndermek ilk nedeni ortadan kaldırır.

50035 Invalid Form Body

Gönderdiğiniz gövde şemaya uymuyor. Hata nesnesindeki errors alanı hangi alanın neden reddedildiğini gösterir. discord.js rehberindeki örnekte bir nesne, mesaj kimliği yerine verildiği için yol [object Object] içeriyor ve 50035 dönüyor. Embed alan sınırları, boş alan adları ve yanlış tipte kimlikler sık nedenlerdir. Embed kuralları için Discord embed mesaj oluşturma yazısına bakın.

Hataları kodda yakalamak

discord.js

discord.js, API hatalarını DiscordAPIError olarak fırlatır ve code özelliğinde JSON hata kodunu taşır. Sabitler için RESTJSONErrorCodes kullanabilirsiniz:

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

async function guvenliDm(user, metin) {
  try {
    await user.send(metin);
    return true;
  } catch (error) {
    if (error.code === RESTJSONErrorCodes.CannotSendMessagesToThisUser) {
      return false; // DM kapalı, sessizce geç
    }
    throw error;
  }
}

async function guvenliSil(message) {
  await message.delete().catch((error) => {
    if (error.code !== RESTJSONErrorCodes.UnknownMessage) console.error(error);
  });
}

Yakalanmamış hataları görmek için discord.js rehberi ana dosyaya process.on('unhandledRejection', ...) dinleyicisi eklemeyi önerir. Hata çıktısındaki path ve method alanları sorunun hangi uç noktada çıktığını gösterir.

discord.py

discord.py'de HTTP hataları discord.HTTPException sınıfından türer; 403 için discord.Forbidden, 404 için discord.NotFound fırlatılır. İstisnanın status alanı HTTP kodunu, code alanı Discord JSON kodunu verir:

import discord

async def guvenli_dm(user: discord.User, metin: str) -> bool:
    try:
        await user.send(metin)
        return True
    except discord.Forbidden as e:
        if e.code == 50007:
            return False  # DM kapalı veya ortak sunucu yok
        raise
    except discord.HTTPException as e:
        print('Discord hatası:', e.status, e.code, e.text)
        return False

Sık Sorulan Sorular

Missing Access ile Missing Permissions arasındaki fark nedir?

Belgede 50001 "Missing access", 50013 ise "You lack permissions to perform that action" olarak geçer. Pratikte 50001 botun kaynağa hiç erişemediği durumlarda, 50013 ise kaynağı görse de istenen işlemi (rol verme, mesaj silme gibi) yapma izni olmadığında görülür.

Botum 4004 ile kapanıyor, ne yapmalıyım?

4004 "Authentication failed" demektir: Identify yükündeki token yanlıştır. Developer Portal'dan yeni token alıp ortam değişkeninizi güncelleyin. Bu kodda otomatik yeniden bağlanma denenmemelidir.

Tüm hata kodlarının listesine nereden bakabilirim?

Tam ve güncel liste Discord'un "Opcodes and Status Codes" sayfasındadır. discord.js kullanıyorsanız aynı kodların sabit adlarını RESTJSONErrorCodes enum'unda bulabilirsiniz.

5xx hatası alırsam ne yapmalıyım?

5xx kodları Discord tarafındaki sorunları gösterir ve nadirdir. 502 için belge biraz bekleyip yeniden denemenizi önerir. Bu sırada isteği sınırsız döngüde tekrar etmeyin; artan aralıklarla birkaç kez denemek yeterlidir.

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: Etkileşim başarısız oldu hatası · Discord rate limit ve 429 · Discord intent nedir · Bot izinleri ve rol hiyerarşisi · Bot token güvenliği · Discord sharding nedir · Discord webhook ve bot entegrasyonu