REST API geliştirirken hata yönetimi, yalnızca sunucu tarafında sorunları yakalamak değil, aynı zamanda istemciye neyin yanlış gittiğini açıkça bildirmektir. Standart HTTP durum kodlarını doğru kullanmak ve anlamlı hata mesajları oluşturmak, API'nizin kullanılabilirliğini, bakımını ve güvenliğini doğrudan etkiler. Bu yazıda, REST API'lerde hata kodlarını standartlaştırma ve hata mesajlarını anlamlı hale getirme konusunda pratik ipuçları ve kontrol listesi sunuyoruz.
HTTP Durum Kodlarının Doğru Kullanımı
Her HTTP durum kodu belirli bir anlam taşır. Yaygın hatalardan biri, tüm hatalar için 500 Internal Server Error döndürmek veya başarısız bir validasyon için 200 OK kullanmaktır. İşte temel kodlar:
- 2xx Başarılı: 200 OK (GET, PUT), 201 Created (POST), 204 No Content (DELETE).
- 3xx Yönlendirme: API'lerde nadiren kullanılır; 301/302 için uygun durumlarda tercih edin.
- 4xx İstemci Hatası: 400 Bad Request (genel geçersiz istek), 401 Unauthorized (kimlik doğrulama eksik), 403 Forbidden (yetki yok), 404 Not Found, 405 Method Not Allowed, 409 Conflict (çakışma), 422 Unprocessable Entity (validasyon hatası), 429 Too Many Requests (rate limiting).
- 5xx Sunucu Hatası: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout.
Örneğin, bir kaynak bulunamadığında 404 döndürmek standarttır. Ancak bir işlem kısıtlaması varsa 403 değil 429 kullanılmalıdır.
Anlamlı Hata Mesajı Yapısı
Sadece durum kodu yeterli değildir; istemciye hatayı anlayıp çözmesi için yeterli bilgi vermelisiniz. RFC 7807 (Problem Details) standardı, hata yanıtları için yaygın bir modeldir:
{
"type": "https://example.com/errors/invalid-email",
"title": "Geçersiz E-posta",
"status": 422,
"detail": "Sağlanan e-posta adresi formatı geçersiz.",
"instance": "/api/users",
"errors": {
"email": "E-posta alanı '@' işareti içermelidir."
}
}
Bu yapı, hatanın türünü, insan okunabilir başlığını, HTTP durum kodunu, detaylı açıklamayı ve hata kaynağını içerir. Özellikle validasyon hatalarında alan bazlı hataları eklemek, istemcinin hızlıca düzeltme yapmasını sağlar.
Sık Yapılan Hatalar ve Kaçınılması Gerekenler
- Güvenlik açıkları: Hata mesajlarında hassas bilgiler (stack trace, veritabanı sorguları, API anahtarları) paylaşmayın. Örneğin, "SQL hatası: ..." yerine "İşlem sırasında bir hata oluştu." kullanın.
- Tutarsız kod kullanımı: Aynı tür hata için farklı durum kodları döndürmeyin. Örneğin, validasyon hatalarını her zaman 422 ile temsil edin.
- Eksik hata alanları: Hata yanıtında yalnızca "message" göndermek yetersizdir; hata türü, detay ve kaynak bilgisi ekleyin.
- Çok dilli destek eksikliği: Uygulamanız birden çok dil kullanıyorsa, hata mesajlarını Accept-Language başlığına göre yerelleştirin.
Pratik Kontrol Listesi
API'nizde hata yönetimini iyileştirmek için aşağıdaki adımları izleyin:
- HTTP durum kodlarını standartlara uygun olarak atayın (her kaynak türü için ayrı kod).
- Hata yanıtlarınızda her zaman bir
type(hata türü URI'si) vetitle(kısa başlık) alanı kullanın. - Validasyon hatalarında, hangi alanın neden geçersiz olduğunu belirten bir
errorsnesnesi ekleyin. - Hata mesajlarında teknik detayları gizleyin; kullanıcıya yalnızca ne yapması gerektiğini anlatan bilgiler verin.
- Rate limiting aşıldığında 429 hatası döndürün ve
Retry-Afterbaşlığı ekleyin. Bu konuda REST API Rate Limiting yazımıza göz atabilirsiniz. - Merkezi bir hata yönetim middleware'i oluşturun. Express.js REST API'lerinde Merkezi Hata Yönetimi makalesi bu konuda rehberlik edebilir.
- JWT ile kimlik doğrulama hatalarında (401) geçersiz token mesajını netleştirin. REST API'lerde JWT ile Güvenli Kimlik Doğrulama yazımızda daha fazla detay bulabilirsiniz.
Örnek Hata Senaryoları ve Doğru Yanıtlar
| Senaryo | Durum Kodu | Yanıt Gövdesi (kısaltılmış) |
|---|---|---|
| Eksik zorunlu alan | 422 | {"title":"Validation Error","detail":"'name' alanı zorunludur."} |
| Geçersiz kimlik bilgisi | 401 | {"title":"Unauthorized","detail":"Token süresi dolmuş veya geçersiz."} |
| Yetkisiz erişim | 403 | {"title":"Forbidden","detail":"Bu kaynağa erişim yetkiniz yok."} |
| Rate limit aşımı | 429 | {"title":"Too Many Requests","detail":"İstek limitinizi aştınız. Lütfen 60 saniye bekleyin."} |
Sonuç Olarak Değil, Sürekli İyileştirme
Standart hata kodları ve anlamlı mesajlar, API'nizin kalitesini ve geliştirici deneyimini artırır. Hata yanıtlarınızı düzenli olarak gözden geçirin, logları analiz edin ve geri bildirimlere göre iyileştirin. Unutmayın: iyi bir hata mesajı, sorunu çözmeye yardımcı olurken güvenlikten ödün vermemelidir.
Sık Sorulan Sorular
REST API'lerde hangi HTTP durum kodları en sık kullanılır?
En sık kullanılan kodlar: 200 (Başarılı), 201 (Oluşturuldu), 400 (Geçersiz İstek), 401 (Yetkisiz), 403 (Yasak), 404 (Bulunamadı), 422 (İşlenemez Varlık), 429 (Çok Fazla İstek) ve 500 (İç Sunucu Hatası). Doğru kod seçimi API'nin tutarlılığı için kritiktir.
Özel hata kodları eklemeli miyim?
Standart HTTP durum kodları çoğu senaryoyu kapsar. Ancak iş mantığınıza özgü hatalar için yanıt gövdesinde bir 'code' alanı kullanabilirsiniz. Örneğin, 'INVALID_EMAIL' gibi bir kod ekleyerek istemcinin programatik olarak ayırt etmesini sağlayabilirsiniz.
Hata mesajlarında çoklu dil desteği nasıl sağlanır?
İstemcinin 'Accept-Language' başlığını okuyarak mesajları yerelleştirebilirsiniz. Ancak unutmayın: teknik alanlar (type, code) sabit kalmalı, yalnızca 'title' ve 'detail' alanları çevrilmelidir.
Hata mesajlarında güvenlik açısından nelere dikkat edilmelidir?
Kesinlikle stack trace, veritabanı sorguları, API anahtarları veya iç IP adresleri gibi hassas bilgileri paylaşmayın. Hata mesajları yalnızca kullanıcının hatayı anlamasına yetecek kadar bilgi içermeli, sistem iç yapısını ifşa etmemelidir.
