HTTP Durum Kodları (Status Codes)

Bir API'ye istek yaptığınızda, sunucu size sadece veri göndermez. Aynı zamanda bir durum kodu da döner. Bu kod, isteğinizin nasıl sonuçlandığını söyler: Başarılı mı? Hata mı var? Yetkiniz mi yok?

Muhtemelen 404 hatasını daha önce görmüşsünüzdür. Bu bir durum kodu. Bu makalede tüm durum kodu kategorilerini ve en sık karşılaşılanları öğreneceksiniz.

Durum Kodu Nedir?

HTTP durum kodu, sunucunun isteğinize verdiği 3 haneli sayısal yanıttır. Her kod belirli bir anlam taşır.

İstek: GET /urunler/5
Yanıt: 200 OK
       { "id": 5, "ad": "Laptop", "fiyat": 15000 }

Burada 200 durum kodu, OK ise durum mesajı.

Durum Kodu Kategorileri

Durum kodları 5 kategoriye ayrılır. İlk rakam kategoriyi belirler:

Basit kural:

• 2 ile başlıyorsa → Her şey yolunda ✓
• 4 ile başlıyorsa → Siz hata yaptınız ✗
• 5 ile başlıyorsa → Sunucu hata yaptı ✗

2xx - Başarı Kodları

Bu kodları görmek istiyoruz. Her şeyin yolunda gittiğini gösterir.

200 OK

En yaygın durum kodu. İstek başarılı, yanıt gövdesinde veri var.

GET /kullanicilar/1
→ 200 OK
→ { "id": 1, "isim": "Ali", "email": "ali@mail.com" }

Ne zaman döner:

• GET isteği başarılı olduğunda
• PUT/PATCH güncellemesi başarılı olduğunda
• Genel başarı durumlarında

201 Created

Yeni kayıt oluşturuldu. POST isteğinden sonra sıkça görülür.

POST /urunler
Body: { "ad": "Telefon", "fiyat": 8000 }
→ 201 Created
→ { "id": 42, "ad": "Telefon", "fiyat": 8000 }

Ne zaman döner:

• Yeni kullanıcı kaydedildiğinde
• Yeni sipariş oluşturulduğunda
• Yeni içerik eklendiğinde

204 No Content

Başarılı ama döndürülecek içerik yok. Silme işlemlerinde yaygın.

DELETE /yorumlar/55
→ 204 No Content
→ (boş yanıt)

Ne zaman döner:

• DELETE başarılı olduğunda
• Güncelleme yapıldı ama yanıt gerekmediğinde

3xx - Yönlendirme Kodları

İstediğiniz kaynak başka bir yerde. Tarayıcı genellikle otomatik yönlendirir.

301 Moved Permanently

Kalıcı yönlendirme. Kaynak artık başka bir URL'de.

GET http://eski-site.com/sayfa
→ 301 Moved Permanently
→ Location: https://yeni-site.com/sayfa

Örnek: http:// adresine gittiğinizde https:// adresine yönlendirilirsiniz.

302 Found (Temporary Redirect)

Geçici yönlendirme. Kaynak şimdilik başka bir yerde.

GET /promosyon
→ 302 Found
→ Location: /kampanya/yaz-indirimi

Ne zaman döner:

• Geçici kampanya sayfalarına yönlendirme
• Bakım sayfasına yönlendirme

304 Not Modified

Değişiklik yok. Önbellekteki (cache) versiyon hâlâ geçerli.

GET /logo.png
If-Modified-Since: Wed, 21 Oct 2024 07:28:00 GMT
→ 304 Not Modified

Tarayıcı, önceden indirdiği dosyayı kullanmaya devam eder. Bant genişliği tasarrufu sağlar.

4xx - İstemci Hata Kodları

Bu kodlar sizin bir hata yaptığınızı gösterir. URL yanlış, yetkiniz yok, veri eksik...

400 Bad Request

Hatalı istek. Sunucu isteğinizi anlayamadı.

POST /kullanicilar
Body: { isim: Ali }  ← Geçersiz JSON (tırnaklar eksik)
→ 400 Bad Request
→ { "hata": "Geçersiz JSON formatı" }

Yaygın nedenler:

• JSON formatı bozuk
• Zorunlu alan eksik
• Veri tipi yanlış (sayı yerine metin gönderilmiş)

401 Unauthorized

Kimlik doğrulama gerekli. Giriş yapmadınız veya token geçersiz.

GET /hesabim
→ 401 Unauthorized
→ { "hata": "Lütfen giriş yapın" }

Yaygın nedenler:

• Token/API key gönderilmemiş
• Token süresi dolmuş
• Yanlış şifre

Not: "Unauthorized" (yetkisiz) adı biraz yanıltıcı. Aslında "Unauthenticated" (kimliği doğrulanmamış) demek istiyor.

403 Forbidden

Erişim yasak. Kimliğiniz doğrulandı ama bu kaynağa yetkiniz yok.

GET /admin/kullanicilar
→ 403 Forbidden
→ { "hata": "Bu sayfaya erişim yetkiniz yok" }

401 vs 403 farkı:

• 401: Kim olduğunuzu bilmiyoruz → Giriş yapın
• 403: Kim olduğunuzu biliyoruz ama izniniz yok → Yetkiniz yok

Örnek:

• Normal kullanıcı, admin paneline erişmeye çalışıyor → 403
• Giriş yapmamış biri, profil sayfasına erişmeye çalışıyor → 401

404 Not Found

Kaynak bulunamadı. En ünlü hata kodu.

GET /urunler/999999
→ 404 Not Found
→ { "hata": "Ürün bulunamadı" }

Yaygın nedenler:

• URL yanlış yazılmış
• Kaynak silinmiş
• ID mevcut değil

Hoppscotch'ta test:

GET https://jsonplaceholder.typicode.com/posts/999
→ 404 Not Found

405 Method Not Allowed

Metod desteklenmiyor. Bu URL o metodu kabul etmiyor.

DELETE /hakkimizda
→ 405 Method Not Allowed
→ { "hata": "Bu endpoint DELETE metodunu desteklemiyor" }

Örnek:

• Sadece GET destekleyen bir endpoint'e POST yapmak
• Salt okunur bir kaynağı silmeye çalışmak

409 Conflict

Çakışma var. İstek, mevcut durumla çelişiyor.

POST /kullanicilar
Body: { "email": "ali@mail.com" }
→ 409 Conflict
→ { "hata": "Bu email adresi zaten kayıtlı" }

Yaygın nedenler:

• Aynı kullanıcı adı/email ile kayıt
• Aynı ürün kodunu tekrar ekleme
• Versiyon çakışması

422 Unprocessable Entity

İşlenemeyen varlık. Sözdizimi doğru ama içerik mantıksız.

POST /siparisler
Body: { "urunId": 5, "adet": -3 }
→ 422 Unprocessable Entity
→ { "hata": "Adet negatif olamaz" }

400 vs 422 farkı:

• 400: JSON bozuk, parse edilemiyor
• 422: JSON doğru ama iş kurallarına uymuyor

429 Too Many Requests

Çok fazla istek. Rate limit aşıldı.

GET /api/veriler
→ 429 Too Many Requests
→ { "hata": "Dakikada maksimum 60 istek yapabilirsiniz" }

Ne zaman döner:

• API limitini aştığınızda
• Çok hızlı istek yaptığınızda
• DDoS koruması devreye girdiğinde

5xx - Sunucu Hata Kodları

Bu kodlar sunucunun bir sorun yaşadığını gösterir. Sizin hatanız değil.

500 Internal Server Error

Genel sunucu hatası. Bir şeyler ters gitti ama ne olduğu belli değil.

GET /rapor/olustur
→ 500 Internal Server Error
→ { "hata": "Beklenmeyen bir hata oluştu" }

Yaygın nedenler:

• Sunucu kodunda bug
• Veritabanı bağlantı sorunu
• Beklenmeyen durum (exception)

502 Bad Gateway

Geçersiz ağ geçidi. Sunucu, başka bir sunucudan geçersiz yanıt aldı.

GET /api/harici-servis
→ 502 Bad Gateway

Ne zaman döner:

• Proxy/load balancer arkasındaki sunucu çöktüğünde
• Mikroservisler arası iletişim koptuğunda

503 Service Unavailable

Servis kullanılamıyor. Sunucu geçici olarak hizmet veremiyor.

GET /api/veriler
→ 503 Service Unavailable
→ { "hata": "Bakım çalışması devam ediyor" }

Yaygın nedenler:

• Planlı bakım
• Sunucu aşırı yüklenmiş
• Bağımlı servis çalışmıyor

504 Gateway Timeout

Ağ geçidi zaman aşımı. Sunucu, başka bir sunucudan zamanında yanıt alamadı.

GET /api/yavas-islem
→ 504 Gateway Timeout

Ne zaman döner:

• Uzun süren işlemler zaman aşımına uğradığında
• Arka uç servis yanıt vermediğinde

Durum Kodlarını Test Etme

Hoppscotch/Postman'da

İstek yaptığınızda yanıt bölümünde durum kodunu görebilirsiniz:

• Yeşil: 2xx (başarı)
• Sarı/Turuncu: 3xx (yönlendirme)
• Kırmızı: 4xx, 5xx (hata)

httpstat.us ile Test

Bu site, istediğiniz durum kodunu döndürür:

GET https://httpstat.us/200  → 200 OK
GET https://httpstat.us/404  → 404 Not Found
GET https://httpstat.us/500  → 500 Internal Server Error

Hata yönetimi kodunuzu test etmek için kullanışlı.

Özet Tablosu

Sırada Ne Var?

HTTP durum kodlarını öğrendik. Artık bir API yanıtını tam olarak anlayabilirsiniz.

Bir sonraki makalede Query String (sorgu dizisi) kullanımını detaylı inceleyeceğiz.