Bir API'yi kullanan geliştirici için en sinir bozucu şeylerden biri, her uç noktanın hatayı farklı bir biçimde döndürmesidir: bir yerde {"error": "..."}, başka yerde {"message": "..."}, bir başkasında 200 durum koduyla {"success": false}. Problem Details standardı, HTTP API'leri için ortak bir hata dili tanımlar.
Standart: RFC 9457
Problem Details, ilk olarak RFC 7807 ile tanımlandı ve 2023'te yayımlanan RFC 9457 ile güncellendi. Yanıtın içerik tipi application/problem+json olur:
{
"type": "https://ornek.com/hatalar/yetersiz-stok",
"title": "Yetersiz stok",
"status": 409,
"detail": "Ürün 1042 için talep edilen 5 adet, mevcut 2 adet stoktan fazla.",
"instance": "/siparisler",
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Alanlar
| Alan | Anlamı |
|---|---|
| type | Hata türünü tanımlayan URI; dokümantasyona işaret edebilir |
| title | Hata türünün kısa, sabit açıklaması |
| status | HTTP durum kodu |
| detail | Bu olaya özgü, insan tarafından okunabilir açıklama |
| instance | Hatanın oluştuğu kaynak veya istek |
Standart, ek alanlar eklemeye izin verir: traceId, errors gibi. İstemci kodunun hatayı ayırt etmek için title metnine değil, type değerine bakması gerekir.
Doğrulama hataları
Form ve istek doğrulamasında hangi alanın neden hatalı olduğunu bildirmek gerekir:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Bir veya daha fazla doğrulama hatası oluştu.",
"status": 400,
"errors": {
"eposta": ["Geçerli bir e-posta adresi girin."],
"telefon": ["Telefon numarası 10 haneli olmalıdır."]
}
}Bu yapı, arayüzün hata mesajlarını doğrudan ilgili alanın altında göstermesini sağlar. Bkz. form tasarımı.
ASP.NET Core'da kullanım
builder.Services.AddProblemDetails();
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();
app.MapPost("/siparisler", (SiparisDto dto) =>
stokYetersiz
? Results.Problem(title: "Yetersiz stok", statusCode: 409,
type: "https://ornek.com/hatalar/yetersiz-stok")
: Results.Created(...));AddProblemDetails ile beklenmeyen hatalar ve boş durum kodları da otomatik olarak standart formata dönüşür. Merkezi hata yakalama için bkz. hata yönetimi ve middleware.
Güvenlik
- Yığın izi, SQL hatası, sunucu yolu gibi ayrıntılar canlı ortamda asla yanıtta yer almamalıdır. Bkz. OWASP Top 10.
- Bunun yerine bir
traceIddöndürün; ayrıntılar loglarda bu kimlikle bulunur. - Kimlik doğrulama hatalarında fazla bilgi vermeyin ("bu e-posta kayıtlı değil" gibi mesajlar kullanıcı listesini sızdırır).
Doğru durum kodu
Problem Details doğru durum kodunun yerini tutmaz, onu tamamlar. 400 doğrulama, 401 kimlik, 403 yetki, 404 bulunamadı, 409 çakışma, 429 fazla istek, 500 sunucu hatası. Ayrıntılar: HTTP durum kodları.
Sık sorulan sorular
Hata mesajlarını Türkçe mi vermeliyim?
detail ve doğrulama mesajları kullanıcıya gösterilecekse istemcinin diline göre yerelleştirilebilir; type ise dil bağımsız sabit bir tanımlayıcı olarak kalmalıdır.
Mevcut API'mi değiştirirsem istemciler bozulur mu?
Hata formatını değiştirmek de bir sözleşme değişikliğidir. Yeni bir API sürümüyle veya kademeli geçişle yapılmalıdır. Bkz. API versiyonlama.
Sonuç
Standart bir hata formatı, API'yi kullananların hataları tek bir yerde ve tek bir biçimde ele almasını sağlar. Problem Details, bunu sıfırdan icat etmeden yapmanın en kolay ve yaygın yoludur.
