# 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

| Belirti | En sık sebep | Hızlı çözüm | Ayrıntılı rehber |
|---|---|---|---|
| Bot üye listesinde çevrimdışı görünüyor | Program çalışmıyor ya da gateway'e hiç `identify` göndermedi | Terminalde `READY` satırını gör; yalnızca REST çağıran program botu çevrimiçi yapmaz | [Gateway](https://noluyo.net/gelistirici/gateway.md), [Botu açık tut](https://noluyo.net/gelistirici/botu-acik-tut.md) |
| `message.content` boş (`""`) geliyor | `MESSAGE_CONTENT` intent'i kapalı ya da kodda istenmemiş | Portalda **Mesaj içeriği**'ni aç, `intents` değerine ekle ve programı yeniden başlat | [Intent'ler](https://noluyo.net/gelistirici/intentler.md) |
| Gateway `4014` ile kapanıyor | Portalda açılmamış (veya 100+ sunucuda onaylanmamış) ayrıcalıklı intent istendi | Portalda ilgili intent'i aç ya da `intents` değerinden çıkar | [Intent'ler](https://noluyo.net/gelistirici/intentler.md), [Doğrulama](https://noluyo.net/gelistirici/dogrulama.md) |
| Gateway `4004` veya HTTP `401` dönüyor | Token yanlış, yenilenmiş ya da REST başlığında `Bot ` öneki eksik | `.env` içindeki token'ı kontrol et; gerekirse portaldan **Token'ı yenile** yap | [Kimlik doğrulama](https://noluyo.net/gelistirici/kimlik.md) |
| Gateway `4011` ile kapanıyor | Aynı bot iki yerde birden çalışıyor (örneğin bilgisayar + VPS) | Eski kopyayı durdur; iki süreç birbirini düşürmeye devam eder | [Shard'lar](https://noluyo.net/gelistirici/shardlar.md), [Botu açık tut](https://noluyo.net/gelistirici/botu-acik-tut.md) |
| HTTP `403` (`missing_access` / `missing_permissions` / `role_hierarchy`) | Kanalı görme izni yok, işlem izni yok ya da botun rolü aşağıda | Kanalda `ViewChannel` ver, rolde izni aç ya da bot rolünü yukarı taşı | [İzinler](https://noluyo.net/gelistirici/izinler.md) |
| HTTP `429` (`rate_limited` / `slowmode`) | Hız sınırı aşıldı veya kanalda yavaş mod açık | `retry_after` saniye bekle ya da resmi `noluyo-bot` kuyruğunu kullan | [Hız sınırları](https://noluyo.net/gelistirici/rate-limit.md) |
| Eğik çizgi (`/`) komutu listede görünmüyor | Komut kaydedilmedi, kanalda `UseApplicationCommands` kapalı ya da 60 sn dolmadı | `commands.sync` çıktısını kontrol et, 1 dakika bekle, kanal izinlerine bak | [Komutlar](https://noluyo.net/gelistirici/komutlar.md), [Komut izinleri](https://noluyo.net/gelistirici/komut-izinleri.md) |
| Butona basınca "Bot yanıt vermedi." / etkileşim başarısız | Bot 3 saniye içinde `callback` dönmedi ya da uzun işi yanıttan önce yaptı | Önce `i.defer()` (`type: 5` / `6`) gönder, ağır işi ondan sonra çalıştır | [Etkileşimler](https://noluyo.net/gelistirici/etkilesimler.md), [Bileşenler](https://noluyo.net/gelistirici/bilesenler.md) |
| Ses kanalına girmiyor ya da ses çıkmıyor | `Connect` / `Speak` izni yok, `ffmpeg` kurulu değil ya da HTTP ses rotası çağrıldı | Gateway'den `op 4` gönder, `VOICE_JOIN_ERROR` koduna bak ve `ffmpeg -version` dene | [Ses](https://noluyo.net/gelistirici/ses.md) |

## 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](https://noluyo.net/gelistirici/botu-acik-tut.md) 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](https://noluyo.net/gelistirici/intentler.md#mesaj-icerigi-kurali):

- `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](https://noluyo.net/gelistirici/uygulamalar) 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](https://noluyo.net/gelistirici/dogrulama.md) 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](https://noluyo.net/gelistirici/izinler.md#rol-siralamasi) 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](https://noluyo.net/gelistirici/kutuphane-js.md) ve [Python](https://noluyo.net/gelistirici/kutuphane-python.md) 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](https://noluyo.net/gelistirici/komutlar.md).

## 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](https://noluyo.net/gelistirici/etkilesimler.md) sayfasında.
- [HTTP ile teslim](https://noluyo.net/gelistirici/http-teslim.md) 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](https://noluyo.net/gelistirici/ses.md) sayfasında.

## Bu sayfayı yapay zekaya verirsen

> **İpucu:** Botun hata verdiğinde terminal çıktısını (içinden `.env` ve token'ı çıkararak!) bu sayfayla birlikte yapay zekaya yapıştır. Özellikle `missing_permissions` ile `role_hierarchy` farkını ve `4014` intent kuralını kontrol etmesini iste.

## Sırada ne var

- [Hatalar](https://noluyo.net/gelistirici/hatalar.md): API'deki tüm makinece okunur hata kodlarının tam referans tablosu
- [SSS](https://noluyo.net/gelistirici/sss.md): izinler, mesajlar, DM kuralları ve ephemeral mesajlar hakkında sık sorulan sorular
- [İzinler](https://noluyo.net/gelistirici/izinler.md): izin bitleri ve rol hiyerarşisi hesaplaması