API Hata Yönetimi Stratejileri ve HTTP Status Kodları

API Hata Yönetimi: REST Tabanlı Sistemlerde Doğru Strateji Seçmek

Bir REST API geliştirirken en kritik kararlardan biri, hata yanıtlarını nasıl yapılandıracağınızıdır. İyi tasarlanmış bir hata yönetimi stratejisi, hem geliştirici deneyimini iyileştirir hem de uygulama stabilitesini artırır. HTTP status kodları, error handling patterns ve client-side yönetim yöntemleri arasındaki farkları anlamak, doğru mimariye ulaşmanız için gereklidir.

HTTP Status Kodları ve Anlamları: Hangileri Nerede Kullanılmalı?

HTTP status kodları, API iletişiminin temel dilidir. Ancak her durumda hangi kodu kullanacağınız, uygulamanızın karmaşıklığı ve client'ın ne kadar ayrıntılı bilgi alması gerektiğine bağlıdır.

2xx Başarı Kodları (200 OK, 201 Created, 204 No Content) temel seviyedir. Ancak fark şudur: 200 OK genelde veri döndürülen istekler için, 201 Created yeni kaynak oluşturmada, 204 No Content silme işlemlerinde kullanılır. Örneğin, bir POST isteğine 201 dönmek, client'a "işlem başarılı ve yeni bir kaynak oluşturdum" mesajını iletir.

4xx Client Hataları daha ayrıntılı sınıflandırma gerektirir:

400 Bad Request – Geçersiz parametre veya syntax hatası
401 Unauthorized – Kimlik doğrulama gerekli veya başarısız
403 Forbidden – Kimliği doğrulandı ancak izin yok
404 Not Found – Kaynak mevcut değil
429 Too Many Requests – Rate limiting (istek sınırı aşıldı)

5xx Server Hataları (500 Internal Server Error, 503 Service Unavailable) uygulamanızın sorun yaşadığını gösterir. Burada önemli nokta, 500 yerine daha spesifik kodlar (503, 502) kullanmanın client'ın yeniden deneme stratejisini belirlemesine yardımcı olmasıdır.

Hata Yanıtı Yapılandırması: Standart Format Belirleme

Status kodunu belirledikten sonra, response body'sinde ne tür bilgiler göndereceğiniz kadar önemlidir. Tutarsız hata formatları, client-side hata yönetimini zorlaştırır.

İki yaygın yaklaşım vardır:

Basit Format	Detaylı Format
Sadece error message gönderme	Error code, message, field details ve timestamp
Hızlı, ancak debugging zorlaştırır	Client'ın hatasını tam olarak anlayabilir
Örnek: {"error": "Invalid email"}	Örnek: {"code": "INVALID_INPUT", "message": "Email format invalid", "field": "email", "timestamp": "2024-01-15T10:30:00Z"}

Detaylı format avantajlı olmakla birlikte, her API çağrısında ek veri taşır. Karar verirken, uygulamanızın karmaşıklığını ve client cihazlarının bant genişliğini göz önüne alın.

Hata Yanıtı Standardizasyonu

Tüm hataları aynı yapıda döndürün (örneğin her zaman JSON)
Error code'ları sabit ve insan tarafından okunabilir tutun (VALIDATION_ERROR, AUTH_FAILED, vb.)
Locale desteği eklemek istiyorsanız, message yerine error_code'u translate edin
Sensitive bilgiler (internal stack trace, database details) asla expose etmeyin

Client Tarafında Hata Yönetimi: Handling Patterns

API hata yönetimi sadece server-side değildir. Client-side pattern'ler, kullanıcı deneyimini belirler.

Retry Stratejileri zorunludur. 5xx hatalar genelde geçici olduğundan, exponential backoff kullanarak yeniden denemeler yapılmalıdır. Örneğin 1. deneme 1 saniye sonra, 2. deneme 2 saniye sonra, 3. deneme 4 saniye sonra. Ancak 4xx hataları retry'a alınmamalıdır—bunlar client tarafında düzeltilecek sorunlardır.

User-Facing Mesajlar da kritiktir. API'den gelen technical error message'ı direkt göstermeyin. Yerine, kullanıcının anlayacağı Türkçe mesajlar hazırlayın: "Lütfen email adresinizi kontrol edin" (400 Bad Request yerine).

Circuit Breaker Pattern, tekrarlanan başarısız istekler için önem kazanır. Eğer API sürekli 5xx dönüyorsa, client'ın istekleri göndermeyi kesmesi, hem sunucuyu korur hem de kullanıcıya hızlı geri bildirim sağlar.

Logging ve Monitoring

Tüm 5xx hataları server-side'de loglayın ve alert gönderin
4xx hataların desenlerini izleyin (403 artışı = yetkilendirme sorunu)
Client-side JavaScript hataları da capture edin (örneğin timeout'lar)
Rate limiting'e takılan client'ları tanımla ve sorun çözümle

Senaryo Karşılaştırması: Üç API Tasarım Yaklaşımı

Yaklaşım	Hata Format	Avantaj	Dezavantaj
Minimal	HTTP status kodu sadece	Düşük bandwith	Hangi alanın hatalı olduğu belli değil
Standart	Status + error code + message	Dengeli, çoğu durumda yeterli	Validation hatalarında field detayı yok
Kapsamlı	Status + detaylı JSON (field errors, suggestions)	Client debugging kolay, UX'i iyileştirebilir	Response size büyür, kompleks logic

Çoğu modern uygulama, standart yaklaşımdan başlayıp, ihtiyaç halinde kapsamlı formata geçişi tercih eder.

Sonuç olarak, API hata yönetimi seçimi, tek bir "doğru" cevap değildir. Uygulamanızın ölçeği, client sayısı ve kullanıcı tabanının tekniklik seviyesi bu kararları şekillendirir. HTTP status kodlarını doğru kullanmak, hata response'larını standardize etmek ve client-side handling'e yatırım yapmak, isterseniz eğitim alırken karşılaştırdığınız diğer backend konuları kadar önemlidir. Sağlam bir hata yönetimi stratejisi, ölçeklenebilir ve bakımlanabilir API'ler inşa etmenin temelini oluşturur.