Problem Details API hatalarında neyi standartlaştırır?
Problem Details, HTTP API hata yanıtlarının gövdesi için ortak bir JSON modelidir. RFC 9457, application/problem+json medya türünü tanımlar. Bu model HTTP durum kodunun yerine geçmez; hatanın uygulamaya özgü açıklamasını taşır.
Bir endpoint errorMessage, diğeri message, bir başkası ise iç içe result.error döndürüyorsa istemcide her çağrı için farklı ayrıştırma kodu oluşur. Ortak sözleşme, bu dallanmayı azaltmak için kullanılabilir. Bütün hataları aynı mesaja dönüştürmek gerekmez: kullanıcıya hangi girdiyi düzelteceğini söyleyen bir doğrulama hatasıyla, beklenmedik sunucu arızasının ayrıntı seviyesi aynı olmamalıdır.
Örnek bir doğrulama yanıtı nasıl görünür?
Aşağıdaki yanıt, sıfır adetli bir sipariş gönderildiği varsayımsal senaryo içindir. Adresler ve olay kimliği örnektir; gerçek bir API endpoint'ini tarif etmez:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: tr
Cache-Control: no-store
{
"type": "https://api.example.com/problems/invalid-quantity",
"title": "Sipariş miktarı geçersiz",
"status": 422,
"detail": "quantity alanına 1 veya daha büyük bir tam sayı girin.",
"instance": "urn:uuid:4f238586-e93d-4d84-9f16-38f0a438c2fe",
"errors": [
{ "pointer": "/quantity", "code": "minimum", "minimum": 1 }
]
}
type hata türünü, instance belirli hata oluşumunu tanımlar. title kısa başlık, detail ise bu oluşuma ait açıklamadır. status verilirse gerçek HTTP yanıt koduyla aynı olmalıdır. errors, pointer ve code alanlarının bu örnekteki biçimi uygulamanın sözleşmesidir; RFC her API için bu doğrulama şemasını zorunlu kılmaz.
Bu sözleşmeyle quantity alanına odaklanabilir, minimum koşulunu gösterebilir ve kullanıcının diğer girdilerini koruyabilirsiniz. Erişilebilir form rehberi, hata mesajını ilgili alanla ilişkilendirmeyi açıklar. Bütün formu temizlemek, hatayı düzeltmek için gerekli değildir.
Hata ayrıştırılırken HTTP durumu nasıl korunur?
fetch, 4xx veya 5xx yanıtı geldi diye kendiliğinden reddedilmez; response.ok ya da status kontrolü gerekir. Fetch kullanım rehberi, ağ hatası ile HTTP hata yanıtının farkını açıklar.
Aşağıdaki yardımcı yalnızca başarısız bir Response için çağrılacak şekilde yazılmıştır. Hata gövdesi boş, bozuk JSON veya bir proxy'nin HTML yanıtı olabilir. Önce medya türünü kontrol eder, ayrıştırma başarısız olsa da HTTP kodunu korur:
async function readApiFailure(response) {
if (response.ok) throw new TypeError('Expected a failed response');
const mediaType = (response.headers.get('content-type') ?? '')
.split(';')[0].trim().toLowerCase();
let body = null;
if (mediaType === 'application/problem+json') {
try {
const value = await response.json();
if (value && typeof value === 'object' && !Array.isArray(value)) {
body = value;
}
} catch {
// HTTP durumu, bozuk hata gövdesinde de kullanılabilir.
}
}
return {
status: response.status,
type: typeof body?.type === 'string' ? body.type : 'about:blank',
title: typeof body?.title === 'string' ? body.title : 'İstek tamamlanamadı',
};
}
Bu küçük yardımcı tam bir RFC doğrulayıcısı veya bütün istekleri yöneten bir istemci değildir. Uygulamaya özgü errors uzantısının doğrulanması ayrı yapılmalıdır. Bir Response gövdesini de yalnızca bir kez tüketebileceğinizi hesaba katın; aynı yanıtı sonra tekrar response.json() ile okumaya çalışmayın.
Kullanıcıya gösterilecek metin nasıl seçilmeli?
İstemci davranışını çevrilebilir title metnine göre dallandırmayın. Kendi API'nizin bilinen type değerlerini ürün mesajlarına eşleyin. Örnekteki invalid-quantity türü bir miktar alanı uyarısına dönüşebilir; bilinmeyen tür genel bir başarısızlık mesajına düşebilir. Hata türünün dokümantasyon adresini her hata oluştuğunda otomatik indirmek gerekmez.
Sunucudan gelen metni HTML olarak yerleştirmeyin. Normal metin olarak gösterin ve tanımadığınız bir servisin detail alanını doğrudan son kullanıcıya taşımadan önce uygunluğunu değerlendirin. OWASP hata yönetimi rehberi, hata ayrıntılarının bilgi sızdırma riskini ele alır.
Beklenmedik arızada istemciye SQL metni, bağlantı ayrıntısı veya stack trace göndermek yerine sınırlı bir açıklama ve destek için olay kimliği verin. Ayrıntılı teşhis bilgisini yetkisi sınırlı sunucu günlüklerinde tutun. Günlüklere de gereksiz kişisel veri ve gizli değer yazmamak gerekir.
Bu sözleşme nasıl test edilir?
Örnek istemciyi yalnızca düzgün bir 422 gövdesiyle denemeyin. Aynı HTTP durumunda bozuk JSON, boş içerik ve beklenmeyen alan türleri gönderin. application/problem+json; charset=utf-8 gibi parametreli medya türünü ve gövdede farklı status yazıldığı durumu da kapsayın. Yardımcı bu son durumda gerçek yanıt durumunu döndürür.
Retry kararı hata JSON'unun varlığına göre verilmez. Yetki eksikliği, kullanıcı girdisi ve geçici servis sorunu farklı toparlanma yolları gerektirir. 401 ve 403 rehberi kimlik ve yetki ayrımını, retry rehberi ise yeniden denemenin sınırlarını açıklar.
Sık sorulan sorular
Hata JSON’u dönüyorsa HTTP 200 kullanılabilir mi? Başarısız isteği 200 ile gizlemek ortak HTTP davranışlarını bozar. Uygun hata durumunu kullanın; gövde onu açıklar.
errors alanı her Problem Details yanıtında olmak zorunda mı? Hayır. Bu örnekte uygulamanın tanımladığı bir uzantıdır ve kendi şeması belgelenmelidir.
Ağ hatasında Problem Details okunabilir mi? Yanıt alınamadıysa Response gövdesi yoktur. Ağ/iptal hatasıyla sunucunun döndürdüğü HTTP hatasını ayrı yönetin.

