# Hatalar

Başarısız her istek aynı biçimde bir JSON gövdesi döndürür:

```json
{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "errors": { "content": "required" }
}
```

| Alan | Anlamı |
|---|---|
| `code` | Değişmeyen, makinece okunur kod. Kararını buna göre ver. |
| `message` | Geliştiriciler için açıklama. Değişebilir, kullanıcıya olduğu gibi gösterme. |
| `errors` | Yalnızca `validation_failed` ile: alan başına bir hata kodu. |
| `retry_after` | Yalnızca hız sınırı ve geçici engel hatalarında: beklenecek saniye. |

`message` metinleri İngilizcedir. Tek istisna `maintenance`'tır: `Accept-Language` başlığı İngilizceyi öne çıkarıyorsa İngilizce, aksi halde Türkçe gelir.

## Alan hata kodları

`validation_failed` ile gelen `errors` içinde görülür:

| Kod | Anlamı |
|---|---|
| `required` | Alan zorunlu ve boş |
| `invalid` | Değer geçersiz |
| `too_short` | Çok kısa |
| `too_long` | Çok uzun |
| `taken` | Bu değer alınmış, örneğin kullanıcı adı |

Listeler ve sorgu parametreleri için de aynı biçim kullanılır: `limit` aralık dışındaysa `{"limit":"invalid"}` döner.

## Kimlik ve erişim

| HTTP | Kod | Anlamı | Ne yapmalı |
|---|---|---|---|
| 401 | `unauthorized` | Token eksik, yanlış veya artık geçersiz. | Tekrar deneme. Token'ı ve `Bot ` önekini kontrol et; gerekirse portaldan yenile. |
| 403 | `bot_forbidden` | Bu rota botlara kapalı. | Rotayı kullanma. Bota açık rotalar [REST referansında](https://noluyo.net/gelistirici/api.md). |
| 403 | `temporarily_banned` | Bu IP adresinden çok fazla reddedilmiş bot isteği geldi. | `retry_after` kadar bekle, reddedilen istekleri tekrarlamayı bırak. Bkz. [Hız sınırları](https://noluyo.net/gelistirici/rate-limit.md). |
| 403 | `missing_access` | Kanalı görme izni yok. | Bota `ViewChannel` verilmeli. |
| 403 | `missing_permissions` | Gereken izin yok ya da bot susturulmuş. | Rotanın izinleri [REST referansında](https://noluyo.net/gelistirici/api.md) yazar. |
| 403 | `role_hierarchy` | Hedef veya rol, botun rütbesinden aşağıda değil. | Botun rolü yukarı taşınmalı. Bkz. [İzinler](https://noluyo.net/gelistirici/izinler.md). |

## Bulunamayanlar

Üyesi olmadığın bir sunucu `unknown_guild`, görmediğin bir sunucunun kanalı `unknown_channel` döner; böylece var olup olmadıkları açığa çıkmaz.

| HTTP | Kod | Anlamı |
|---|---|---|
| 404 | `not_found` | Böyle bir rota yok. Yöntem yanlışsa da bu döner. |
| 404 | `unknown_guild` | Sunucu yok ya da üyesi değilsin. |
| 404 | `unknown_channel` | Kanal yok ya da erişimin yok. |
| 404 | `unknown_role` | Rol yok. |
| 404 | `unknown_member` | Kişi bu sunucunun üyesi değil. |
| 404 | `unknown_user` | Kullanıcı yok. |
| 404 | `unknown_message` | Mesaj bu kanalda yok. |
| 404 | `unknown_ban` | Bu kullanıcı yasaklı değil. |
| 404 | `unknown_application` | Uygulama yok ya da senin değil. |
| 404 | `unknown_command` | Komut yok ya da bu kapsamda değil: sunucu komutu global rotadan, global komut sunucu rotasından bulunmaz. |

## İstek hataları

| HTTP | Kod | Anlamı |
|---|---|---|
| 400 | `invalid_body` | Gövde tek bir geçerli JSON nesnesi değil, bir alanın türü yanlış (örneğin metin yerine sayı olarak ID) ya da multipart parçası tanınmıyor. |
| 400 | `validation_failed` | Bir veya daha fazla alan geçersiz; ayrıntı `errors` içinde. |
| 413 | `body_too_large` | Gövde çok büyük. |
| 413 | `file_too_large` | Dosya yükleme sınırını aşıyor. |
| 400 | `invalid_channel_type` | İşlem bu kanal türünde yapılamaz, örneğin ses kanalına mesaj. |
| 400 | `unknown_emoji` | Emoji geçersiz, bulunamadı veya bot kullanamıyor. |
| 400 | `invalid_image` | Görsel PNG, JPEG, WebP veya GIF değil. |
| 413 | `image_too_large` | Görsel boyut sınırını aşıyor. |

## Mesajlar, roller ve moderasyon

| HTTP | Kod | Anlamı |
|---|---|---|
| 403 | `not_author` | Yalnızca kendi mesajını düzenleyebilirsin. |
| 403 | `system_message` | Sistem mesajı üzerinde bu işlem yapılamaz. |
| 400 | `ephemeral_forbidden` | Kanala giden mesajda `flags: 64` (ephemeral) gönderildi; kanal mesajının gösterileceği tek bir kişi yoktur. `flags` alanını çıkar. |
| 400 | `fanout_too_large` | Mesajın embed ve bileşenleri, sunucunun üye sayısıyla çarpılınca [yayılma bütçesinin](https://noluyo.net/gelistirici/rate-limit.md#embed-ve-bilesenlerin-yayilma-butcesi) 30 saniyesinden fazla tutuyor. `max_bytes` o kanalın alabileceği en büyük boyuttur; embed'leri küçült. |
| 400 | `automod_blocked` | Sunucunun otomatik moderasyonu mesajı engelledi. `message`, sunucunun yazdığı metin olabilir. Kural ayrıca göndereni susturabilir. Sunucu sahibi ve `ManageGuild` izni olanlar muaftır. |
| 400 | `messages_too_old` | Toplu silmede 14 günden eski mesaj var. |
| 400 | `max_pins` | Kanal sabitleme sınırında. |
| 400 | `too_many_reactions` | Mesaj farklı emoji sınırında. |
| 400 | `everyone_role` | `@everyone` silinemez, verilemez, adı veya sırası değiştirilemez. |
| 400 | `managed_role` | Yönetilen rol silinemez, verilemez, alınamaz, otomatik atanamaz. |
| 400 | `max_roles` | Sunucu rol sınırında. |
| 400 | `max_channels` | Sunucu kanal sınırında. |
| 400 | `max_overwrites` | Kanal, izin geçersiz kılma sınırında. |
| 400 | `cannot_target_self` | Bu işlem kendine uygulanamaz. |
| 403 | `cannot_timeout` | Sahip ve yöneticiler susturulamaz. |
| 400 | `not_in_voice` | Kişi seste değil. |
| 400 | `owner_cannot_leave` | Sunucunun sahibi sunucudan ayrılamaz. |

## Uygulamalar ve bot ekleme

| HTTP | Kod | Anlamı |
|---|---|---|
| 403 | `bots_closed` | Yalnızca platform anahtarı kapalıyken döner; açık platformda üretilmez. |
| 403 | `bot_developer_required` | Yalnızca kapalı dönemde üretilir; açık platformda her doğrulanmış hesap uygulama oluşturabilir. |
| 403 | `developer_terms_required` | Hesap geliştirici sözleşmesini kabul etmedi; portaldan kabul et. |
| 403 | `email_not_verified` | E-posta doğrulanmamış. |
| 403 | `guest_not_allowed` | Misafir hesabı uygulama oluşturamaz. |
| 400 | `max_applications` | Hesap, uygulama sınırında. |
| 403 | `bot_private` | Bu botu yalnızca sahibi ekleyebilir. |
| 403 | `banned` | Bot bu sunucudan yasaklı. |
| 400 | `bot_in_guild` | Bot zaten sunucuda. |
| 400 | `bot_guild_limit` | Bot, sunucu sınırında. |
| 403 | `member_list_intent_required` | Üye listesi `GUILD_MEMBERS` ister: portalda açık, 100 sunucudan itibaren de onaylı olmalı. |
| 400 | `intent_approval_required` | Bot 100 ya da daha çok sunucuda ve ayrıcalıklı intent henüz onaylanmadı. |
| 400 | `review_requirements` | Doğrulama önkoşulları eksik (`errors` içinde `public`, `description`, `avatar`, `privacy_url`, `support_url`, `owner_mfa`). [Doğrulama](https://noluyo.net/gelistirici/dogrulama.md) |
| 400 | `review_pending` | Bu uygulama için zaten bekleyen bir doğrulama başvurusu var. [Doğrulama](https://noluyo.net/gelistirici/dogrulama.md) |
| 409 | `review_decided` | Bu doğrulama başvurusu zaten sonuçlandırılmış. [Doğrulama](https://noluyo.net/gelistirici/dogrulama.md) |
| 400 | `max_commands` | Bu kapsam bu türden komut sınırında: 100 eğik çizgi komutu, her menü türünden 15. [Komutlar](https://noluyo.net/gelistirici/komutlar.md#limitler) |
| 403 | `command_permission_escalation` | Kişiye döner, bota değil: komut izinlerini düzenleyen kişi, komutun `default_member_permissions` bitlerine kendisi sahip değil. Sahip ve `Administrator` bunu almaz. [Komut izinleri](https://noluyo.net/gelistirici/komut-izinleri.md) |

## Bileşene basma

Bunlar botuna değil, basan kişiye döner. Ayrıntı [Bileşenler](https://noluyo.net/gelistirici/bilesenler.md) sayfasında.

| HTTP | Kod | Anlamı |
|---|---|---|
| 404 | `component_not_found` | Mesajda artık bu `custom_id` yok: bot butonu kaldırmış ya da mesajı bir bot göndermemiş. |
| 400 | `component_disabled` | Bileşen kapalı. |
| 409 | `application_unavailable` | Mesajı gönderen uygulama silinmiş, kapatılmış ya da botu artık burada değil. |
| 429 | `interaction_busy` | Basmalar uygulamanın ya da tüm botların sınırına takıldı; [HTTP ile teslimde](https://noluyo.net/gelistirici/http-teslim.md#kisi-ne-gorur) adresine aynı anda 16 teslim gidiyor ya da adresinin yanıtı tüm botların tavanına takıldı. `retry_after` kadar bekle. |
| 504 | `application_no_response` | Uygulamanın [etkileşim adresi](https://noluyo.net/gelistirici/http-teslim.md#yanit-ver) 3 saniyede kullanılabilir bir yanıt vermedi, yanıtı reddedildi ya da adres art arda hata verdiği için şu an aranmıyor. Sebebi teslim günlüğü söyler. |
| 403 | `cannot_dm` | Kişi DM'de bu botu engellemiş; engeli kaldırana dek basamaz. |

## Komut çalıştırma

Bunlar da botuna değil, komutu çalıştıran kişiye döner; olay sana hiç gelmez. Kişi bir komutun boşa gittiğini söylüyorsa sebep çoğunlukla buradadır. Komut çalıştırma ve form gönderme basmalarla aynı sınırları paylaşır, `interaction_busy` burada da gelebilir. [Otomatik tamamlama](https://noluyo.net/gelistirici/otomatik-tamamlama.md) da aynı kodları döner, ama kendi sınırları vardır. Ayrıntı [Komutlar](https://noluyo.net/gelistirici/komutlar.md#komutu-yanitla) sayfasında.

| HTTP | Kod | Anlamı |
|---|---|---|
| 409 | `command_outdated` | Komutu, kişinin ekranı onu yükledikten sonra değiştirdin. Uygulama yeni tanımı alır, uyan değerleri korur ve kişi yeniden gönderir. |
| 403 | `command_forbidden` | Kişi komutu bu kanalda kullanamaz: `UseApplicationCommands` yok, zaman aşımında, bir [komut izni](https://noluyo.net/gelistirici/komut-izinleri.md) kuralı engelliyor ya da `default_member_permissions` bitleri eksik. |
| 400 | `invalid_target` | Seçenekteki ya da menüdeki kullanıcı, rol, kanal veya mesaj kişinin burada gösterebileceği biri değil: üye değil, başka sunucunun rolü, görmediği kanal, `channel_types` dışında bir kanal, başka kanalın mesajı, silinmiş ya da ephemeral mesaj, ya da kişinin `ReadMessageHistory` izni yok. |
| 400 | `command_channel` | Bu kanalda komut çalışmaz. Komutlar sunucunun yazı kanallarında ve kişinin botla açtığı DM'de çalışır; iki kişinin DM'sinde ve grup DM'de değil. |
| 404 | `unknown_command` | Komut silinmiş ya da başka sunucunun; ya da bot sunucudan çıkarılmış veya uygulaması kapalı. DM'de: komut başka botun, sunucu komutu, `contexts` içinde `1` yok ya da `default_member_permissions` dolu. |
| 403 | `missing_access` | DM'de: kişi botla DM'yi kapatmış; yeniden açınca komut çalışır. |
| 403 | `cannot_dm` | DM'de: kişi botu engellemiş; engeli kaldırana dek komut çalıştıramaz. |
| 400 | `modal_expired` | [Form](https://noluyo.net/gelistirici/formlar.md) gönderiminde: form 1 saatten eski, üç kez gönderildi ya da başka bir kişinin veya kanalın. Kişi formu yeniden açar. |

## Etkileşim yanıtları

Bunlar botuna döner. Ne yapacağın [Etkileşimler](https://noluyo.net/gelistirici/etkilesimler.md) sayfasında.

| HTTP | Kod | Anlamı |
|---|---|---|
| 400 | `interaction_token_invalid` | Token bozuk, adresteki kimlikle uyuşmuyor ya da başka bir botun. |
| 400 | `interaction_timeout` | İlk yanıt 3 saniyeyi geçti. |
| 400 | `interaction_already_acknowledged` | Bu etkileşime zaten yanıt verdin. |
| 400 | `interaction_not_acknowledged` | Takip ya da düzenleme ilk yanıttan önce geldi. |
| 400 | `interaction_response_invalid` | `type` bu etkileşime uymuyor, `type: 7`'de `data` yok, `choices` `type: 8` dışında geldi, `type: 9` otomatik tamamlamaya ya da gönderilen forma gitti veya yanında mesaj alanı var, ya da otomatik tamamlamanın token'ıyla takip mesajı veya düzenleme denendi. |
| 400 | `interaction_expired` | Token'ın 15 dakikası doldu. Kişi ephemeral mesajın 15 dakikası dolmuş butonuna bastığında da bunu alır. |
| 400 | `ephemeral_files` | Ephemeral mesajda dosya ya da `attachment://` var; bu mesajın dosya bağlanacak satırı yok. |
| 404 | `unknown_channel` | Ephemeral mesajda: basan kişi artık kanalı görmüyor, ona bir şey gitmedi. |
| 403 | `dm_closed` | DM'de: kişi DM'yi kapattı ya da botu engelledi. Yanıt da gitmez. |

## Özel mesajlar

Bir kişinin botunla açtığı DM'de kendiliğinden yazarken (mesaj, tepki, sabitleme, yazıyor) dönenler. Ayrıntılar [Özel mesajlar](https://noluyo.net/gelistirici/ozel-mesajlar.md) sayfasında.

| HTTP | Kod | Anlamı |
|---|---|---|
| 403 | `dm_closed` | Kişi DM'yi kapattı ya da botu engelledi; ikisi aynı görünür. O kişiye yazmayı bırak, yeniden deneme. |
| 403 | `dm_window_closed` | Kişinin son mesajı, komutu ya da basmasından beri 24 saat geçti. Kişi yeniden yazana dek bekle. |
| 429 | `rate_limited` | `X-RateLimit-Scope: bot` ile: tüm DM'lerindeki serbest yazma sınırı (`dm_send`) doldu. `retry_after` kadar bekle. |

## Etkileşim adresi

Portalda adres kaydedilirken dönenler. Yalnızca hatanın türü söylenir. Ayrıntılar [HTTP ile teslim](https://noluyo.net/gelistirici/http-teslim.md#hatalar) sayfasında.

| HTTP | Kod | Anlamı |
|---|---|---|
| 400 | `endpoint_not_allowed` | Adres https, 443 ve genel bir ad değil, ya da N'oluyo'nun kendi adresi. |
| 400 | `endpoint_unreachable` | Adrese ulaşılamadı ya da 3 saniyede yanıt gelmedi. |
| 400 | `endpoint_bad_response` | Doğru imzalı `PING`'e `200 {"type":1}` dönmedi. |
| 400 | `endpoint_no_signature_check` | Yanlış imzalı isteğe `401` dönmedi: imzayı doğrula. |

## Hız sınırları

| HTTP | Kod | Anlamı |
|---|---|---|
| 429 | `rate_limited` | Hız sınırı aşıldı. `retry_after` kadar bekle. |
| 429 | `slowmode` | Kanalda yavaş mod açık. `retry_after` kadar bekle. |
| 429 | `upload_quota` | Kısa sürede çok fazla dosya yüklendi. `retry_after` kadar bekle. |

Ayrıntılar [Hız sınırları](https://noluyo.net/gelistirici/rate-limit.md) sayfasında.

## N'oluyo ile giriş (OAuth2)

`/oauth2/authorize` ve `/oauth2/@me/*` rotaları standart `{code, message}` döndürür; `/oauth2/token` ve `/oauth2/revoke` ise OAuth2 standardına uygun `{error, error_description}` gövdesi döndürür:

| HTTP | Kod / `error` | Anlamı |
|---|---|---|
| 403 | `oauth_closed` | Yalnızca platform anahtarı kapalıyken döner; açık platformda üretilmez. |
| 400 | `oauth_unknown_client` | `client_id` geçersiz, bulunamadı ya da uygulaması devre dışı. |
| 400 | `oauth_bad_redirect` | `redirect_uri` bu uygulama için kayıtlı değil; sayfa o adrese yönlendirilmez. |
| 400 | `oauth_bad_request` | `response_type=code`, `state`, `code_challenge_method=S256` ya da `scope` geçersiz. |
| 403 | `oauth_user_cap` | Doğrulanmamış uygulama 100 kullanıcı yetki sınırına ulaştı. |
| 403 | `terms_not_accepted` | Kişi güncel kullanım koşullarını henüz kabul etmedi. |
| 403 | `oauth_scope_required` | Erişim token'ı bu rotanın istediği kapsama (`guilds` gibi) sahip değil. |
| 400 | `invalid_request` | `/oauth2/token` ya da `/oauth2/revoke` form gövdesi eksik veya bozuk. |
| 401 | `invalid_client` | `client_id` ya da `client_secret` yanlış veya eksik. |
| 400 | `invalid_grant` | Yetki kodu ya da yenileme token'ı geçersiz, süresi dolmuş veya yeniden kullanılmış. |
| 400 | `unsupported_grant_type` | Yalnızca `authorization_code` ve `refresh_token` desteklenir. |
| 429 / 503 | `temporarily_unavailable` | Token hız sınırı aşıldı (`Retry-After` kadar bekle) ya da hizmet bakımda. |

## Ses (VOICE_JOIN_ERROR)

Gateway üzerinden `op 4` gönderdiğinde bağlantı kapanmaz; bir engel varsa `VOICE_JOIN_ERROR` olayı içinde şu kodlardan biri gelir. Ayrıntılar [Ses](https://noluyo.net/gelistirici/ses.md#hata-kodlari-voice_join_error) sayfasında.

| Kod | Anlamı |
|---|---|
| `unknown_guild` | Sunucu yok ya da bot üye değil. |
| `unknown_channel` | Kanal bu sunucuda yok. |
| `invalid_channel_type` | Kanal bir ses kanalı (`type: 2`) değil. |
| `missing_access` | Botun bu kanalı görme (`ViewChannel`) izni yok. |
| `missing_permissions` | Botun kanalda `Connect` izni yok ya da zaman aşımında. |
| `channel_bot_limit` | Bu ses kanalında en çok sayıda bot var. |
| `guild_bot_limit` | Bu sunucuda en çok sayıda bot seste. |
| `app_voice_limit` | Uygulama eşzamanlı ses bağlantısı sınırında. |
| `bot_voice_full` | Platform genelindeki bot ses kapasitesi dolu. |
| `voice_unavailable` | Ses hizmeti o an kullanılamıyor. |

## Gateway kapanış kodları

Bu sayfadaki kodlar REST içindir. Gateway bağlantısı `4000` ile başlayan kapanış kodlarıyla kapanır: neyin yeniden bağlanmayı gerektirdiği [Gateway](https://noluyo.net/gelistirici/gateway.md) sayfasındaki tabloda, adları [Olaylar](https://noluyo.net/gelistirici/olaylar.md#close-codes) sayfasında.

## Sunucu tarafı

| HTTP | Kod | Anlamı | Ne yapmalı |
|---|---|---|---|
| 503 | `maintenance` | N'oluyo bakımda; bot ve uygulama rotaları bu yanıtı verir. | Bir süre bekleyip yeniden dene. `GET /api/v1/maintenance` kimlik istemez ve `enabled` alanında bakımın sürüp sürmediğini söyler. |
| 503 | `voice_unavailable` | Ses hizmeti bu sunucuda kullanılamıyor. | Daha sonra yeniden dene. |
| 500 | `internal` | Beklenmeyen bir hata oldu. | Biraz bekleyip yeniden dene; sürerse bize bildir. |

## Bu sayfayı yapay zekaya verirsen

> **İpucu:** Hata yönetimi yazdırırken yapay zekaya `res.status` yanında gövdedeki `code` ve `errors` alanlarını da okumasını, `401` ve `403` hatalarını döngüde tekrar denememesini, `429` yanıtlarında ise `retry_after` süresini beklemesini söyle.

## Sırada ne var

- [Sık hatalar](https://noluyo.net/gelistirici/sik-hatalar.md): en çok karşılaşılan belirtilerin adım adım çözümü
- [Hız sınırları](https://noluyo.net/gelistirici/rate-limit.md): `429` yanıtları, kovalar ve geçersiz istek sınırı
- [Gateway](https://noluyo.net/gelistirici/gateway.md): `4000` serisi WebSocket kapanış kodları ve yeniden bağlanma kuralları