HTTP Durum Kodları Rehberi: 1xx ile 5xx Arası

HTTP durum kodları, bir sunucunun istemciye (tarayıcı, API istemcisi vb.) verdiği üç haneli yanıt numaralarıdır. Her istek-yanıt döngüsünde bir durum kodu döner ve bu kod, isteğin başarılı olup olmadığını, yönlendirilip yönlendirilmediğini veya bir hata oluşup oluşmadığını belirtir. Web geliştiricileri için bu kodları anlamak, hata ayıklama ve API tasarımı açısından kritik öneme sahiptir.

1xx — Bilgilendirme (Informational)

İstek alındı ve işlenmeye devam ediyor. Tarayıcılar tarafından genellikle kullanıcıya gösterilmez.

• 100 Continue: Sunucu istek başlıklarını aldı, istemci gövdeyi gönderebilir
• 101 Switching Protocols: Sunucu protokol değiştirmeyi kabul etti (örneğin HTTP'den WebSocket'e)
• 103 Early Hints: Tarayıcının bazı kaynakları önceden yüklemeye başlamasını sağlar

2xx — Başarılı (Success)

İstek başarıyla alındı, anlaşıldı ve işlendi.

• 200 OK: En yaygın başarı kodu. İstek başarıyla tamamlandı ve yanıt gövdesinde veri var
• 201 Created: Yeni bir kaynak oluşturuldu (POST isteklerinde yaygın)
• 204 No Content: İstek başarılı ancak döndürülecek içerik yok (DELETE isteklerinde yaygın)

3xx — Yönlendirme (Redirection)

İsteğin tamamlanması için ek işlem gerekiyor, genellikle başka bir URL'ye yönlendirme.

• 301 Moved Permanently: Kaynak kalıcı olarak taşındı. Arama motorları yeni URL'yi dizine alır. SEO için en önemli yönlendirme türüdür
• 302 Found: Geçici yönlendirme. Kaynak geçici olarak başka bir adreste. Arama motorları orijinal URL'yi korur
• 304 Not Modified: Kaynak değişmedi, tarayıcı önbelleğini kullanabilir. Performans için kritiktir — gereksiz veri transferini önler
• 307 Temporary Redirect: 302 ile aynı ancak HTTP metodu (GET/POST) korunur
• 308 Permanent Redirect: 301 ile aynı ancak HTTP metodu korunur

301 ve 302 Farkı

SEO açısından bu ayrım çok önemlidir:

• 301: "Bu sayfa kalıcı olarak taşındı." Arama motoru otoritesini (link juice) yeni URL'ye aktarır
• 302: "Bu sayfa geçici olarak başka yerde." Arama motoru orijinal URL'yi dizinde tutar

4xx — İstemci Hatası (Client Error)

Hatanın kaynağı istemci tarafıdır — yanlış URL, yetersiz yetki veya hatalı istek.

• 400 Bad Request: Sunucu isteği anlayamadı. Eksik parametreler, hatalı JSON formatı gibi nedenlerle oluşur
• 401 Unauthorized: Kimlik doğrulama gerekli. Kullanıcı giriş yapmamış veya token geçersiz
• 403 Forbidden: Kimlik doğrulanmış olsa bile erişim yetkisi yok. 401'den farkı: kimliğinizi biliyorum ama izniniz yok
• 404 Not Found: İstenen kaynak bulunamadı. URL yanlış veya sayfa silinmiş olabilir
• 405 Method Not Allowed: HTTP metodu (GET, POST vb.) bu endpoint için desteklenmiyor
• 408 Request Timeout: Sunucu isteği beklerken zaman aşımına uğradı
• 409 Conflict: İstek, kaynağın mevcut durumu ile çelişiyor (aynı kaydı aynı anda güncelleme gibi)
• 429 Too Many Requests: Rate limiting — çok fazla istek gönderildi, beklemek gerekiyor

401 ve 403 Farkı

Sıkça karıştırılan bu iki kod arasındaki fark:

• 401: "Kim olduğunuzu bilmiyorum, lütfen giriş yapın"
• 403: "Kim olduğunuzu biliyorum ama bu kaynağa erişim yetkiniz yok"

5xx — Sunucu Hatası (Server Error)

Hatanın kaynağı sunucu tarafıdır. İstek geçerli olmasına rağmen sunucu işlemi tamamlayamadı.

• 500 Internal Server Error: Genel sunucu hatası. Uygulama kodu çöktü, beklenmeyen bir durum oluştu
• 502 Bad Gateway: Ara sunucu (reverse proxy, load balancer) arka uç sunucudan geçersiz yanıt aldı
• 503 Service Unavailable: Sunucu geçici olarak hizmet veremiyor. Bakım modu veya aşırı yük nedeniyle oluşur
• 504 Gateway Timeout: Ara sunucu, arka uç sunucudan zamanında yanıt alamadı

API Tasarımında Doğru Kod Kullanımı

RESTful API'lerde doğru HTTP durum kodlarını döndürmek önemlidir:

GET  /users/123       → 200 (kullanıcı bulundu) veya 404 (bulunamadı)
POST /users           → 201 (oluşturuldu) veya 400 (geçersiz veri)
PUT  /users/123       → 200 (güncellendi) veya 404 (bulunamadı)
DELETE /users/123     → 204 (silindi) veya 404 (bulunamadı)
POST /login           → 200 (başarılı) veya 401 (hatalı kimlik bilgileri)