Hızlı Özet (TL;DR)
RESTful API mimarilerinde her HTTP isteği, istemciye işlemin sonucunu standart bir HTTP durum koduyla (Status Code) bildirmelidir. Yapılan en yaygın hata; hata durumlarında dahi gövde içinde { success: false } döndürerek HTTP 200 OK yanıtı vermektir. Başarılı veri oluşturmada 201 Created, doğrulama hatalarında 422 Unprocessable Entity, yetki eksikliğinde 401/403 kullanılmalı; hata yanıtları ise RFC 7807 Problem Details standardına göre yapılandırılmalıdır.
HTTP Durum Kodları Sınıfları ve Doğru Kullanım Kılavuzu
HTTP protokolünde durum kodları 5 ana sınıfa ayrılır. REST API tasarımında en sık kullanılan kodlar şunlardır:
| Durum Kodu | Anlamı | Hangi Durumda Kullanılmalı? | İdeal Yanıt Gövdesi |
|---|---|---|---|
| 200 OK | Başarılı | Kaynak başarıyla okundu veya güncellendi | Talep edilen veri nesnesi |
| 201 Created | Oluşturuldu | POST ile yeni bir kaynak başarıyla üretildi | Oluşturulan nesne ve Location başlığı |
| 204 No Content | İçerik Yok | DELETE veya işlem başarılı ancak dönecek veri yok | Boş yanıt gövdesi |
| 400 Bad Request | Hatalı İstek | İstemcinin gönderdiği JSON sözdizimsel olarak bozuk | Hata detay nesnesi |
| 401 Unauthorized | Yetkisiz | Kimlik doğrulama yapılmamış (Token yok/geçersiz) | Yetkilendirme hatası açıklaması |
| 403 Forbidden | Yasaklandı | Kimlik doğrulanmış ancak kaynağa yetkisi yok | Erişim engeli sebebi |
| 404 Not Found | Bulunamadı | İstenen URI veya ID veritabanında mevcut değil | Kaynak bulunamadı mesajı |
| 422 Unprocessable | İşlenemez Veri | JSON geçerli ancak iş kuralları ve validasyon geçersiz | Alan bazlı validasyon hataları |
| 500 Internal Error | Sunucu Hatası | Beklenmeyen kod istisnası (Exception) oluştu | Genel sistem hatası (Hassas veri gizlenerek) |
RFC 7807: Problem Details Standardı ile Hata Yanıtı Tasarımı
Her geliştiricinin farklı bir hata JSON formatı uydurması istemci (frontend/mobil) entegrasyonlarını zorlaştırır. IETF tarafından yayınlanan RFC 7807 (Problem Details for HTTP APIs) standardı tek tip kurumsal hata formatı sunar:
{
"type": "https://api.maysayazilim.com/errors/validation-failed",
"title": "İş Kuralları Doğrulama Hatası",
"status": 422,
"detail": "Gönderilen sipariş verisinde kritik alanlar eksik veya geçersiz.",
"instance": "/orders/create/req-98412",
"invalid_params": [
{
"name": "vergiNo",
"reason": "Vergi numarası 10 haneli nümerik olmalıdır."
},
{
"name": "miktar",
"reason": "Sipariş miktarı 0'dan büyük olmalıdır."
}
]
}
REST API Hata Yönetiminde Altın Kurallar
1. 200 OK İçinde Hata Gizlemeyin
Bazı eski mimarilerde ağ geçitlerinin veya frontend kütüphanelerinin hata yakalamasını engellemek için HTTP 200 dönülüp { "status": "error" } yazılır. Bu yaklaşım HTTP önbelleklemesini bozar, API Gateway izlemelerini yanıltır ve mikroservis iletişiminde hataların sessizce yutulmasına sebep olur.
2. Güvenlik Sebebiyle 500 Yanıtlarında Stack Trace Sızdırmayın
Üretim ortamında oluşan beklenmedik hatalarda veritabanı bağlantı dizesi, dosya yolları veya kod satır numaraları (Stack Trace) asla istemciye döndürülmemelidir. Bunun yerine benzersiz bir traceId dönülerek hata merkezi log sistemine yazılmalıdır.
Kurumsal web projelerinizde yüksek standartlı, ölçeklenebilir ve entegrasyona hazır API mimarileri geliştirmek için Özel Yazılım Geliştirme sayfamızı ziyaret edebilirsiniz.