REST API geliştirirken hata yönetimi, çoğu zaman göz ardı edilen ancak kullanıcı deneyimini ve hata ayıklama sürecini doğrudan etkileyen kritik bir konudur. Yanlış HTTP durum kodu kullanımı veya anlamsız hata mesajları, istemci tarafında kafa karışıklığına ve geliştirici ekiplerde zaman kaybına yol açar. Peki, REST API'lerde hatalar nasıl yönetilmeli, hangi durum kodları hangi senaryolarda kullanılmalı ve hata mesajları nasıl yapılandırılmalı? Bu yazıda, uluslararası standartlara uygun, tutarlı ve kullanışlı bir hata yönetim sistemi için adım adım ilerleyeceğiz.
HTTP Durum Kodlarını Doğru Eşleştirin
Her hata senaryosu için uygun HTTP durum kodunu seçmek, API'nizin anlaşılabilirliğini artırır. Aşağıda en sık kullanılan durum kodlarını ve kullanım alanlarını bulabilirsiniz:
| Durum Kodu | Açıklama | Kullanım Senaryosu |
|---|---|---|
| 400 Bad Request | İstek geçersiz veya hatalı | Eksik parametre, hatalı JSON formatı, geçersiz veri türü |
| 401 Unauthorized | Kimlik doğrulama başarısız | Geçersiz token, eksik API anahtarı |
| 403 Forbidden | Yetkilendirme reddedildi | Token geçerli ancak kullanıcının bu kaynağa erişim izni yok |
| 404 Not Found | Kaynak bulunamadı | Yanlış URL, silinmiş kaynak |
| 409 Conflict | Çakışma / Kaynak mevcut | Aynı email ile kayıt, versiyon çakışması |
| 422 Unprocessable Entity | İstek gövdesi doğrulama hatası | Validasyon hataları (örn. şifre çok kısa) |
| 429 Too Many Requests | Rate limit aşıldı | Çok fazla istek gönderilmesi |
| 500 Internal Server Error | Sunucu hatası | Beklenmeyen istisnalar, veritabanı bağlantı hatası |
Bu tablodaki eşleştirmeler, REST API tasarımında yaygın kabul gören en iyi uygulamalardır. 401 ve 403 arasındaki farka dikkat edin: 401 kimlik doğrulama eksikliğini, 403 ise yetki eksikliğini belirtir. Örneğin, kullanıcı giriş yapmamışsa 401, giriş yapmış ancak admin panelini görüntüleme yetkisi yoksa 403 dönülmelidir.
Anlamlı ve Tutarlı Hata Mesajları Oluşturun
Hata durum kodları tek başına yeterli değildir. Hatanın nedenini ve nasıl çözüleceğini açıklayan bir hata mesajı gövdesi sağlamalısınız. Bunun için en yaygın standart RFC 7807 (Problem Details for HTTP APIs) kullanılabilir. Örnek bir hata yanıtı:
{
"type": "https://api.example.com/errors/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'email' field must be a valid email address.",
"instance": "/api/users",
"errors": [
{
"field": "email",
"message": "Geçerli bir e-posta adresi giriniz."
}
]
}
Bu yapı sayesinde istemci, hatayı programatik olarak işleyebilir ve kullanıcıya anlamlı bir geri bildirim gösterebilir. Ayrıca errors dizisi ile birden fazla validasyon hatasını tek seferde raporlamak mümkündür. Bu yaklaşım, Airtable ve Bubble ile CRUD uygulaması gibi no-code projelerde bile backend'de tutarlı hata yönetimi sağlamanın temelini oluşturur.
Global İstisna Yakalama ile Hataları Merkezileştirin
Her endpoint'te ayrı ayrı try-catch blokları kullanmak yerine, global bir istisna yakalayıcı (exception handler) oluşturun. Bu sayede tüm hatalar aynı formatta dönülür ve kod tekrarı azalır. Örneğin Spring Boot'ta @ControllerAdvice, Node.js Express'te middleware, .NET Core'da ExceptionFilter kullanabilirsiniz. Ayrıca beklenmeyen 500 hatalarını da burada yakalayarak kullanıcıya teknik detay göstermeden genel bir “Bir hata oluştu” mesajı dönebilirsiniz.
Hata yönetiminin yanı sıra, frontend tarafında hataların doğru işlenmesi de önemlidir. Örneğin, React useState Hook ile state yönetimi yazımızda hata state'lerinin nasıl tutulması gerektiğini anlatıyoruz. API'den gelen hata yanıtları, bu state üzerinden kullanıcıya gösterilebilir.
Hata Mesajlarında Dikkat Edilmesi Gerekenler
- Kullanıcıya yönelik mesajlar ile geliştiriciye yönelik detaylar ayrılmalıdır. İstemciye dönen mesajlar anlaşılır ve eyleme dönüştürülebilir olmalı (ör. “Email alanı boş bırakılamaz”). Geliştirici loglarına ise daha teknik bilgiler (stack trace, request ID) eklenebilir.
- Güvenlik açıklarına neden olabilecek bilgileri (veritabanı sorgusu, dosya yolu, tablo adı) asla istemciye göndermeyin. Bu, 500 hatalarında sık yapılan bir hatadır.
- Dil desteği sunuyorsanız hata mesajlarını kullanıcının tercih ettiği dilde dönebilirsiniz. Bunun için Accept-Language header'ını kullanabilirsiniz.
- Hata kodu ekleyerek belirli hatalara özel aksiyon alınmasını sağlayın. Örneğin “AUTH_EXPIRED” kodu ile istemcinin token yenileme akışı başlatması istenebilir.
Sık Yapılan Hatalar
- 200 OK dönüp gövdede hata mesajı içeren başarısız işlemler (ör. { success: false, data: null }). Bu, doğru HTTP semantiğine aykırıdır.
- 401 ve 403’ü karıştırmak.
- Validasyon hataları için 400 kullanmak yerine 422 kullanmamak (400 genel hatalar, 422 validasyon için idealdir).
- Hata mesajlarını aynı formatta dönmemek (bazen string, bazen nesne).
- Rate limit aşıldığında Retry-After header'ı eklememek.
API Hata Yönetimini Test Edin
Yazdığınız hata yönetimi mekanizmasını otomatik testlerle doğrulayın. Her durum kodu için uygun yanıtın dönüldüğünü, hata mesajlarının beklendiği gibi olduğunu kontrol edin. Postman veya curl ile manuel testlerin yanı sıra unit testler ve entegrasyon testleri ile de sağlamlaştırabilirsiniz. Unutmayın, iyi bir hata yönetimi API'nizin kalitesini bir üst seviyeye taşır.
Bu rehberde anlatılanları uygulayarak REST API'nizdeki hataları standart, anlaşılır ve güvenli hale getirebilirsiniz. Doğru durum kodları ve anlamlı hata mesajları, API tüketicilerinin hayatını kolaylaştırır ve hata ayıklama süresini kısaltır.
Sık Sorulan Sorular
REST API'de hata durum kodları nasıl seçilir?
Hatanın türüne göre uygun HTTP durum kodu kullanılmalıdır. Örneğin, geçersiz istek için 400, kimlik doğrulama hatası için 401, yetki hatası için 403, kaynak bulunamadı için 404, validasyon hatası için 422 ve sunucu hatası için 500 kullanabilirsiniz.
Hata mesajı yapısı nasıl olmalıdır?
Hata mesajlarında en azından bir hata kodu, anlamlı bir açıklama ve varsa hatayla ilgili alan bilgisi bulunmalıdır. RFC 7807 standardı (Problem Details) bu yapıyı sağlar ve tutarlılık açısından önerilir.
401 Unauthorized ile 403 Forbidden arasındaki fark nedir?
401 Unauthorized, kimlik doğrulama eksikliğini belirtir; kullanıcı giriş yapmamış veya geçersiz token göndermiştir. 403 Forbidden ise kullanıcı kimliği doğrulanmış ancak bu kaynağa erişim yetkisi olmadığı anlamına gelir.
Global hata yakalama neden önemlidir?
Global hata yakalama, tüm hataların merkezi bir noktada aynı formatta dönülmesini sağlar. Kod tekrarını azaltır, beklenmeyen hataları güvenli bir şekilde yönetir ve API genelinde tutarlılık oluşturur.