REST API tasarlarken hata yönetimi, kullanıcı deneyimini ve API güvenilirliğini doğrudan etkiler. Anlamsız 500 hatası yerine, doğru HTTP durum kodları ve tutarlı bir hata yanıt yapısı sunmak, hem istemci tarafında hata ayıklamayı kolaylaştırır hem de API'nizin profesyonelliğini gösterir. Bu yazıda, REST API hata yönetiminde en iyi pratikleri adım adım inceleyecek ve hemen uygulayabileceğiniz bir kontrol listesi sunacağız.
HTTP Durum Kodlarının Doğru Kullanımı
Her hata durumu için uygun HTTP durum kodunu seçmek, API'nizin anlaşılırlığını artırır. İşte sık kullanılan durum kodları ve anlamları:
- 400 Bad Request: İstemci tarafından gönderilen veri geçersiz (örneğin, eksik alan, hatalı JSON). Input validation işlemlerinde kullanılır. REST API'lerde Input Validation konusunda daha fazla bilgi bulabilirsiniz.
- 401 Unauthorized: Kimlik doğrulama başarısız (token eksik veya geçersiz). JWT Token Yönetimi makalemizde güvenli authentication ipuçlarına göz atabilirsiniz.
- 403 Forbidden: Kimlik doğrulama tamam ancak yetki yok (rol veya izin eksik).
- 404 Not Found: Kaynak mevcut değil. Ancak, varlığı gizlemek için 401/403 kullanılabilir (güvenlik gereksinimlerine göre).
- 409 Conflict: Kaynak durumuyla çelişen bir istek (örneğin, aynı email ile kayıt).
- 422 Unprocessable Entity: İstek gövdesi doğru ancak iş mantığı hatası (örneğin, minimum stok miktarı altında sipariş).
- 429 Too Many Requests: Rate limit aşıldığında kullanılır. REST API Rate Limiting yazımızda algoritma karşılaştırmasını bulabilirsiniz.
- 500 Internal Server Error: Sunucu tarafında beklenmeyen hata. Detaylı hata mesajı döndürülmemeli, loglanmalı.
Hata Yanıtı Formatı: JSON API Standardı
Tüm hata yanıtlarında tutarlı bir JSON şeması kullanmak, istemci tarafında hata yönetimini kolaylaştırır. Önerilen yapı:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email alanı geçerli bir email adresi olmalıdır.",
"details": [
{
"field": "email",
"message": "Geçersiz format"
}
],
"status": 422
}
}- code: Makine tarafından okunabilir hata kodu (örn. "VALIDATION_ERROR", "AUTH_EXPIRED").
- message: İnsan tarafından okunabilir genel açıklama.
- details: (Opsiyonel) Alan bazlı hatalar veya alt hatalar dizisi.
- status: HTTP durum kodu (isteğe bağlı, genelde header'da da gelir).
Validation Hataları İçin Ayrıntılı Geri Bildirim
Input validation hatalarında, hangi alanın neden geçersiz olduğunu belirtmek, istemci geliştiriciler için zaman kazandırır. Örneğin:
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Doğrulama hatası",
"details": [
{ "field": "username", "message": "Kullanıcı adı en az 3 karakter olmalıdır." },
{ "field": "password", "message": "Şifre en az 8 karakter içermelidir." }
]
}
}Bu yaklaşım, GraphQL vs REST karşılaştırmasında da vurgulandığı gibi, REST'in net hata mesajları sunma avantajını ortaya koyar.
Güvenlik Açısından Hata Yönetimi
Hata mesajlarında iç sistem detayları (stack trace, SQL sorguları, dosya yolları) asla döndürülmemelidir. 500 hatalarında sadece "Bir hata oluştu" gibi genel bir mesaj verilmeli, gerçek hata detayları sunucu tarafında loglanmalıdır. Ayrıca, kimlik doğrulama hatalarında (401) kaynağın var olup olmadığını ima etmemek için 404 yerine 401 kullanmak daha güvenlidir.
Hata Yönetimi Kontrol Listesi
API'nizde aşağıdaki maddeleri kontrol ederek hata yönetimini iyileştirebilirsiniz:
- ☐ Tüm endpoint'lerde doğru HTTP durum kodları kullanılıyor mu?
- ☐ Hata yanıtları tutarlı bir JSON şemasına sahip mi?
- ☐ Validation hataları için alan bazında detaylı mesaj döndürülüyor mu?
- ☐ 500 hatalarında stack trace veya iç detaylar gizleniyor mu?
- ☐ Rate limit aşıldığında 429 kodu ve Retry-After header'ı ekleniyor mu?
- ☐ Hata kodları (error code) makine tarafından okunabilir ve dokümante edilmiş mi?
- ☐ CORS hataları düzgün yönetiliyor mu?
- ☐ Hata mesajları kullanıcıya uygun dilde ve kültüre duyarlı mı?
- ☐ Hata logları merkezi bir sistemde toplanıyor ve izleniyor mu?
- ☐ API'niz hata durumlarıyla ilgili dokümantasyon içeriyor mu?
Sık Yapılan Hatalar ve Kaçınılması Gerekenler
- Tüm hatalarda 500 dönmek: İstemcinin hatanın türünü anlamasını engeller, hata ayıklamayı zorlaştırır.
- Hata mesajında HTML döndürmek: API yanıtları JSON/XML olmalı, HTML değil.
- Detaylı hata mesajlarını üretim ortamında göstermek: Güvenlik açığı oluşturur.
- Farklı hata formatları kullanmak: Her endpoint farklı yapı dönerse istemci tarafı karmaşıklaşır.
- 401 ile 403'ü karıştırmak: 401 authentication hatası, 403 authorization hatasıdır.
Bu ipuçlarını uygulayarak REST API'nizin hata yönetimini profesyonel seviyeye taşıyabilirsiniz. Unutmayın, iyi bir hata yönetimi, iyi bir API tasarımının ayrılmaz parçasıdır.
Sık Sorulan Sorular
REST API hatalarında hangi HTTP durum kodları kullanılmalı?
Hatanın türüne göre: 400 (Bad Request) validation için, 401 (Unauthorized) kimlik doğrulama başarısızlığı, 403 (Forbidden) yetki yok, 404 (Not Found) kaynak bulunamadı, 409 (Conflict) çakışma, 422 (Unprocessable Entity) iş mantığı hatası, 429 (Too Many Requests) rate limit aşımı ve 500 (Internal Server Error) sunucu hatası.
Hata yanıtı JSON formatı nasıl olmalı?
Tutarlı bir şema kullanın: error nesnesi içinde code (makine okunabilir), message (insan okunabilir), details (alan bazlı hatalar için dizi) ve status (HTTP kodu) alanları bulunmalıdır.
Validation hatalarında ayrıntılı mesaj vermek gerekli mi?
Evet, hangi alanın neden geçersiz olduğunu belirtmek istemci geliştiriciler için çok faydalıdır. details dizisinde field ve message çiftleri gönderilmelidir.
500 hatalarında detaylı bilgi döndürmek güvenli mi?
Hayır, 500 hatalarında stack trace gibi iç detaylar döndürülmemelidir. Sadece genel bir hata mesajı verin, detayları sunucu tarafında loglayın.
401 ve 403 arasındaki fark nedir?
401 (Unauthorized) kimlik doğrulama başarısız olduğunda kullanılır (örneğin token eksik). 403 (Forbidden) kimlik doğrulama başarılı ama kaynağa erişim yetkisi yoksa kullanılır.
