REST API'lerde hata yönetimi, istemci ve sunucu arasındaki iletişimin güvenilirliğini ve kullanıcı deneyimini doğrudan etkiler. Standart HTTP durum kodları ve tutarlı hata yanıtı formatları kullanmak, API tüketicilerinin hataları hızlıca anlamasını ve düzeltmesini sağlar. Bu yazıda, etkili bir hata yönetimi stratejisi için pratik ipuçlarını ve kontrol listesini bulacaksınız.
Neden Standart HTTP Durum Kodları Kullanmalısınız?
HTTP protokolü, her durum için belirlenmiş kodlar sunar. API’nizde bu kodlara sadık kalmak, istemci tarafında beklenti oluşturur ve hata ayıklamayı kolaylaştırır. Örneğin, 400 Bad Request istemcinin yanlış istek gönderdiğini belirtirken, 500 Internal Server Error sunucu tarafındaki bir sorunu işaret eder. Standart dışı kodlar (örneğin 999) kullanmak, çoğu HTTP istemcisinin bu durumu tanıyamamasına yol açar.
En Sık Kullanılan HTTP Durum Kodları ve Anlamları
| Durum Kodu | Açıklama | Kullanım Alanı |
|---|---|---|
| 200 OK | Başarılı istek | GET, PUT, PATCH başarılı yanıtları |
| 201 Created | Kaynak başarıyla oluşturuldu | POST istekleri |
| 204 No Content | İstek başarılı, yanıt gövdesi yok | DELETE, güncelleme sonrası |
| 400 Bad Request | İstemci hatası (geçersiz parametre, hatalı JSON) | Validasyon hataları |
| 401 Unauthorized | Kimlik doğrulama gerekli veya başarısız | Eksik/geçersiz token |
| 403 Forbidden | İzin yok (geçerli token ama yetki yok) | Yetkilendirme hataları |
| 404 Not Found | Kaynak bulunamadı | Var olmayan URI |
| 405 Method Not Allowed | HTTP metodu desteklenmiyor | Kullanıcı kaynağı silmeye çalışırsa |
| 409 Conflict | Çakışma (örneğin kullanıcı adı alınmış) | Tekil kısıt ihlalleri |
| 422 Unprocessable Entity | İstek doğru yapılandırılmış ama işlenemiyor | Semantik validasyon hataları |
| 429 Too Many Requests | Rate limit aşıldı | Kısıtlama stratejileri (bkz. REST API'lerde Rate Limiting) |
| 500 Internal Server Error | Sunucu hatası | Beklenmeyen istisnalar |
| 503 Service Unavailable | Sunucu geçici olarak kullanılamıyor | Bakım, aşırı yük |
Hata Yanıtı Formatı Standartları
Hata yanıt gövdesi, hata hakkında yeterli bilgiyi içermeli ancak gereksiz ayrıntılardan kaçınmalıdır. Yaygın bir yaklaşım RFC 7807 (Problem Details) standardını kullanmaktır. Örnek bir JSON yanıtı:
{
"type": "https://api.example.com/errors/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "'email' alanı geçerli bir e-posta adresi olmalıdır.",
"instance": "/api/users",
"errors": {
"email": "Geçersiz format"
}
}Tutarlılık için tüm hata yanıtlarında aynı şablonu kullanın. Hata kodlarını ve mesajlarını istemci tarafında kolayca işlenebilecek şekilde yapılandırın.
Yaygın Hata Yönetimi Hataları
- Yanlış HTTP durum kodu kullanımı: Örneğin
400yerine500dönmek – bu durum istemcinin hatasını sunucu hatası gibi gösterir. - Hata yanıtında hassas bilgi ifşa etmek: Stack trace, SQL sorguları veya dosya yollarını döndürmek güvenlik açığı yaratır.
- Her hata için
200 OKdönmek: Hata bilgisini gövdede taşımak, HTTP protokolünü ihlal eder ve istemcinin hata işlemesini zorlaştırır. - Hata mesajlarını çok genel veya çok spesifik yapmak: Örneğin “Hata oluştu” yetersizken, “Kullanıcı ID 123456 için veritabanı bağlantı havuzu kaynağı tükendi” gereksiz detay içerir.
- Hataları loglamamak: Sunucu tarafındaki hatalar (5xx) mutlaka loglanmalı ve izlenmelidir; aksi halde sorunlar fark edilmez.
Pratik Kontrol Listesi
API’nizin hata yönetimini değerlendirmek için aşağıdaki adımları izleyin:
- Standart durum kodları kullanın: Yukarıdaki tablodaki kodlara sadık kalın; özel kod tanımlamayın.
- Tutarlı yanıt formatı uygulayın: Tüm hata yanıtları aynı JSON yapısında olsun (örneğin
erroralanı). - Hata mesajlarını insan ve makine okuyabilir yapın:
messagealanı insan için,codealanı ise programatik işleme için kullanılabilir. - Kimlik doğrulama ve yetkilendirme hatalarını ayırın:
401(eksik/geçersiz token) ve403(yetki yok) arasındaki farkı netleştirin. OAuth 2.0 entegrasyonu bu ayrımı doğru yapmanıza yardımcı olur. - Rate limit hatalarını belirtin:
429durum kodu ile birlikteRetry-Afterbaşlığını ekleyin. Detaylı bilgi için REST API'lerde Rate Limiting yazımıza göz atın. - API Gateway kullanıyorsanız hata yönetimini katmanlara ayırın: Gateway seviyesinde genel hataları (örneğin
502) ve servis seviyesinde iş hatalarını yönetin. Mikroservislerde API Gateway Deseni yazımızdan faydalanabilirsiniz. - Hataları loglayın ve izleyin: Tüm 5xx hatalarını merkezi bir log sistemine gönderin; hata oranlarını izleyin.
- Dökümantasyonu güncel tutun: Olası hata kodlarını ve açıklamalarını API belgenizde listeleyin.
Sonuç
Etkili hata yönetimi, API kullanıcılarının sorunları hızlıca çözmesini sağlar ve geliştirici deneyimini iyileştirir. Standart durum kodları, tutarlı yanıt formatı ve yukarıdaki kontrol listesini uygulayarak REST API'nizi daha güvenilir hale getirebilirsiniz.
Sık Sorulan Sorular
REST API'lerde hangi HTTP durum kodları en sık kullanılır?
En sık kullanılan durum kodları 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 422 (Unprocessable Entity), 429 (Too Many Requests) ve 500 (Internal Server Error) olarak sıralanabilir. Her biri belirli bir senaryoyu ifade eder.
401 Unauthorized ile 403 Forbidden arasındaki fark nedir?
401 Unauthorized, istemcinin kimlik doğrulama bilgisi sağlamadığı veya geçersiz bir token gönderdiği durumlarda dönülür. 403 Forbidden ise istemcinin kimliği doğrulanmış olsa bile işlemi gerçekleştirme yetkisi olmadığı anlamına gelir.
Hata yanıtında stack trace döndürmek neden yanlıştır?
Stack trace, sunucu iç yapısı, dosya yolları ve uygulama mantığı hakkında bilgi ifşa eder. Bu, saldırganların sistemi daha kolay hedef almasını sağlar. Ayrıca gereksiz bant genişliği tüketir. Hata yanıtında yalnızca hata kodu, açıklaması ve varsa hangi alanın hatalı olduğu gibi bilgiler yer almalıdır.
Rate limiting hatası (429) gönderirken hangi başlığı eklemeliyim?
429 Too Many Requests yanıtına ek olarak <code>Retry-After</code> başlığını ekleyin. Bu başlık, istemcinin kaç saniye beklemesi gerektiğini belirtir. Ayrıca yanıt gövdesinde limitin ne zaman sıfırlanacağına dair bilgi verebilirsiniz.
