HTTP Durum Kodları: Tam Referans Rehberi

HTTP durum kodları, web sunucusunun bir isteğe nasıl yanıt verdiğini söyleyen 3 haneli sayılardır. Birinci rakam kategorisini belirler: 1xx bilgi, 2xx başarı, 3xx yönlendirme, 4xx istemci hatası, 5xx sunucu hatası.

💡 Hızlı referans için: MagmaNex'in HTTP Status Codes aracını kullanabilirsiniz.

---

1xx — Bilgilendirme

Kod	Adı	Açıklama
100	Continue	Sunucu isteğin başlangıcını aldı, devam et
101	Switching Protocols	WebSocket yükseltmesi gibi protokol değişikliği
103	Early Hints	Link başlıklarını önceden gönder (preload)

Ne Zaman Görürsünüz?

101 Switching Protocols gerçek zamanlı uygulamalarda WebSocket bağlantısı kurulurken görülür.

---

2xx — Başarı

200 OK

En sık karşılaşılan kod. İstek başarıyla tamamlandı.

HTTP/1.1 200 OK
Content-Type: application/json

{"user": "Ahmet", "email": "ahmet@example.com"}

201 Created

POST isteği başarılı ve yeni kaynak oluşturuldu.

HTTP/1.1 201 Created
Location: /api/users/42
Content-Type: application/json

{"id": 42, "message": "Kullanıcı oluşturuldu"}

Ne zaman kullanılır: REST API'de yeni kaynak oluşturan POST endpoint'leri.

204 No Content

İşlem başarılı ama gönderilecek içerik yok.

HTTP/1.1 204 No Content

Ne zaman kullanılır: DELETE işlemleri veya güncelleme sonrasında içerik döndürülmeyecekse.

Diğer 2xx Kodları

Kod	Adı	Açıklama
202	Accepted	İstek alındı ama henüz işlenmedi (asenkron işlemler)
206	Partial Content	Range isteği — video/ses streaming

---

3xx — Yönlendirme

301 Moved Permanently

Kaynak kalıcı olarak taşındı. Google bu URL'i günceller.

HTTP/1.1 301 Moved Permanently
Location: https://yeni-url.com/sayfa

Kullanım: HTTP → HTTPS yönlendirme, eski URL'leri yeni yapıya taşıma.

302 Found

Geçici yönlendirme. Google orijinal URL'i hatırlar.

Kullanım: Bakım sayfasına geçici yönlendirme, login redirect.

304 Not Modified

Kaynağın önbellekteki kopyası hâlâ geçerli, tekrar gönderilmesine gerek yok.

HTTP/1.1 304 Not Modified
ETag: "abc123"
Cache-Control: max-age=3600

Kullanım: Tarayıcı önbelleğini optimize etmek için ETag ve Last-Modified başlıklarıyla birlikte.

307 vs 308

Kod	Adı	Metod Değişimi
307	Temporary Redirect	POST → POST (metod korunur)
308	Permanent Redirect	POST → POST (kalıcı + metod korunur)

---

4xx — İstemci Hataları

400 Bad Request

İstek sözdizimi hatalı veya sunucu anlayamadı.

{
  "error": "Bad Request",
  "message": "email alanı geçerli bir e-posta adresi olmalıdır"
}

Sebepleri: Hatalı JSON formatı, eksik zorunlu alanlar, geçersiz parametre değerleri.

401 Unauthorized

Kimlik doğrulama gerekli ama yapılmamış.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"

401 vs 403 farkı:

• 401: "Kim olduğunu bilmiyorum" — giriş yapman gerekiyor
• 403: "Kim olduğunu biliyorum, izin yok" — giriş yapmış ama yetkisiz

403 Forbidden

Kimlik doğrulandı ama bu kaynağa erişim yasak.

404 Not Found

Kaynak bulunamadı. En sık karşılaşılan hata kodu.

{
  "error": "Not Found",
  "message": "İstenen kullanıcı bulunamadı",
  "id": 9999
}

İpucu: 404 ile 410 (Gone) arasındaki fark: 410 kaynağın kalıcı olarak silindiğini, 404 ise sadece bulunamadığını belirtir.

405 Method Not Allowed

Bu endpoint için HTTP metodu desteklenmiyor.

HTTP/1.1 405 Method Not Allowed
Allow: GET, POST

409 Conflict

İstek mevcut kaynakla çakışıyor.

Örnek: Zaten kayıtlı e-posta adresiyle tekrar kayıt olmaya çalışmak.

{"error": "Conflict", "message": "Bu e-posta adresi zaten kullanılıyor"}

422 Unprocessable Entity

İstek formatı doğru ama içerik semantik olarak geçersiz.

{
  "error": "Validation Failed",
  "errors": [
    {"field": "age", "message": "18 yaşından küçük kullanıcılar kayıt olamaz"},
    {"field": "username", "message": "Özel karakter kullanılamaz"}
  ]
}

400 vs 422 farkı:

• 400: JSON geçersiz / sözdizimi hatası
• 422: JSON geçerli ama içerik kuralları ihlal edilmiş

429 Too Many Requests

Rate limiting devreye girdi.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716700800

Diğer 4xx Kodları

Kod	Adı	Açıklama
408	Request Timeout	İstemci yeterince hızlı göndermedi
410	Gone	Kaynak kalıcı olarak silindi
413	Payload Too Large	Dosya boyutu limitini aştı
415	Unsupported Media Type	Content-Type desteklenmiyor
451	Unavailable For Legal Reasons	Yasal nedenlerle engellendi

---

5xx — Sunucu Hataları

500 Internal Server Error

Sunucuda beklenmedik bir hata oluştu. İstemcinin yapabileceği bir şey yok.

Ne Zaman Görülür: Unhandled exception, veritabanı bağlantı hatası, yapılandırma hatası.

Geliştirici notu: Üretim ortamında 500 hatalarını her zaman loglayın — stack trace detaylarını istemciye GÖNDERMEYİN.

502 Bad Gateway

Ağ geçidi veya proxy geçersiz yanıt aldı.

Ne Zaman Görülür: Nginx upstream bağlantısı koptu, backend çöktü.

503 Service Unavailable

Sunucu geçici olarak hizmet veremiyor — bakım veya aşırı yüklenme.

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

504 Gateway Timeout

Ağ geçidi upstream'den zamanında yanıt alamadı.

502 vs 504 farkı:

• 502: Upstream yanıtladı ama hatalı yanıt verdi
• 504: Upstream hiç yanıtlamadı (timeout)

---

REST API'de Doğru Kod Seçimi

// Kullanıcı oluşturma
router.post('/users', async (req, res) => {
  // Validation hatası → 422
  if (!isValidEmail(req.body.email)) {
    return res.status(422).json({ error: 'Geçersiz e-posta' })
  }
  
  // Tekrar kayıt → 409
  const exists = await User.findOne({ email: req.body.email })
  if (exists) {
    return res.status(409).json({ error: 'E-posta zaten kayıtlı' })
  }
  
  // Başarı → 201
  const user = await User.create(req.body)
  return res.status(201).json(user)
})

// Kullanıcı silme
router.delete('/users/:id', async (req, res) => {
  const deleted = await User.delete(req.params.id)
  
  if (!deleted) {
    return res.status(404).json({ error: 'Kullanıcı bulunamadı' })
  }
  
  // Silme başarılı, içerik yok → 204
  return res.status(204).send()
})

Özet Tablosu

Aralık	Kategori	Örnek
1xx	Bilgilendirme	101 WebSocket
2xx	Başarı	200 OK, 201 Created, 204 No Content
3xx	Yönlendirme	301 Permanent, 302 Temporary
4xx	İstemci Hatası	400, 401, 403, 404, 429
5xx	Sunucu Hatası	500, 502, 503, 504

Tüm HTTP durum kodlarını etkileşimli olarak görmek için MagmaNex'in HTTP Status Codes aracına göz atın.