Bir REST API'de hata yanıtlarını nasıl standartlaştırırsınız? RFC 9457 Problem Details nedir?

Tutarlı hata yanıtları, istemcilerin hataları programatik olarak işleyebilmesini sağlar. Endüstri standardı RFC 9457 Problem Details for HTTP APIs'tır (2023'te RFC 7807'nin yerini aldı). İçerik tipi application/problem+json'dur.

{
  "type": "https://api.ornek.com/errors/insufficient-funds",
  "title": "Yetersiz bakiye",
  "status": 422,
  "detail": "Hesap bakiyesi 30.00 TL, işlem tutarı 50.00 TL.",
  "instance": "/payments/8f2c1",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": [
    { "field": "amount", "code": "exceeds_balance" }
  ]
}

• type: hata türünü tanımlayan URI (makine için sabit anahtar).
• title: kısa, insan okunur özet.
• status, detail, instance: HTTP kodu, bu olaya özel açıklama, ilgili kaynak.
• Ek alanlar (extension members) serbesttir: traceId, errors gibi.

Doğru status code seçimi

Uygulama

• Hataları tek bir yerde üretin: Spring'de @RestControllerAdvice (Spring 6 ProblemDetail sınıfını yerleşik destekler), ASP.NET Core'da AddProblemDetails() + UseExceptionHandler(), Express'te merkezi error middleware.
• 500 hatalarında stack trace veya SQL mesajı dönmeyin; detayı loglayıp istemciye traceId verin.
• 200 OK gövdesinde {"success": false} döndürmek anti-pattern'dir; HTTP durum kodunu doğru kullanın.