HTTP Status Kodları Yetmiyor: API Hataları Neden Daha Detaylı Olmalı

HTTP status kodları API'lerin omurgası gibi görünüyor ama aslında sadece iskelet. Bir istemci 400 aldığında ne yanlış yaptığını bilemez; 500'de ise sunucu tarafında sorun var ama hangisi? Üretim ortamında bu belirsizlik saatler harcatır.

Standart kodlar çok geniş kategorilere ayrılır. 400 Bad Request alanında 50 farklı neden olabilir: geçersiz JSON, eksik alan, yanlış format, yetkisiz erişim... Hata ayıklamak için istemci geliştirici ya tahmin etmek ya da dokümantasyonu çekmek zorunda kalır. Eğer dokümantasyon güncel değilse? O zaman deneme-yanılma başlar.

Bu yüzden başarılı API'ler HTTP kodunun yanında yapılandırılmış bir hata gövdesi dönerler. Örneğin:

1{
2"error": {
3"code": "INVALID_EMAIL_FORMAT",
4"message": "Email alanı geçerli bir e-posta adresi değil",
5"field": "email",
6"timestamp": "2024-01-15T10:30:00Z"
7}
8}

200 OK de tehlikeli olabilir. İstemci başarılı sandığı bir yanıt aslında iş mantığı hatası içerebilir. "Ödeme işlemi başarısız" mesajı 200 içinde gelmişse, istemci bunu başarı olarak kaydedebilir. İyi tasarlanmış API'ler iş hatalarını 4xx ile dönerler ya da yanıt gövdesinde açık bir başarı/başarısızlık bayrağı koyarlar.

Google, Stripe, AWS gibi büyük oyuncuların API'lerini inceledikten sonra ortak bir desen görünür: HTTP kodu + benzersiz hata tanımlayıcı + insan tarafından okunabilir mesaj + gerekirse ek bağlam. Bazıları request ID ekler, böylece sunucu loglarında sorunu anında bulabilirsin.

Praktik olarak, eğer bir API yazıyorsan şu adımları at: HTTP kodunu doğru seç (semantic), hata yanıtında benzersiz bir error code koy, mesajı açık ve eylemli yaz ("Şu alanı kontrol et" yerine "Email alanı geçersiz: örnek@domain.com formatında olmalı"), ve mümkünse bir trace ID ekle. İstemci tarafında da bu yapıyı parse et ve loglama sırasında hata kodunu sakla.

Standart kodlar hala önemli, HTTP protokolünün dilini konuşmak gerekli. Ama onları tek başlarına yeterli görmek, API entegrasyonlarını kırılgan ve hata ayıklaması zor hale getirir. Hata detayı, istemci ve sunucu arasında sağlıklı iletişimin temelini oluşturur.