ASP.NET Core’da ProblemDetails ile Tutarlı API Hataları
ASP.NET Core Minimal API’de ProblemDetails kullanın. Çalıştırılabilir .NET 10 örneğiyle 400, 404 ve 500 yanıtlarını HTTP kodu ve JSON gövdesiyle karşılaştırın.

Erdoğancan Yüksel
1 dakika 38 saniye okuma süresi

Kısa cevap. ProblemDetails, API hataları için ortak bir JSON biçimi sağlar. Sipariş adedi geçersizse 400, sipariş yoksa 404, beklenmeyen bir istisna oluşursa 500 dönebilirsiniz. İstemci önce HTTP durum kodunu okur, ardından gerekiyorsa hata gövdesinden ayrıntı alır.
ProblemDetails gövdesinde hangi alanlar var?
typeproblem türünü tanımlayan bir URI’dir. İstemcinin belirli bir hata için farklı davranması gerekiyorsa belgelenmiş bir türü tanıyabilir.titleproblem türünün kısa açıklamasıdır.detailvarsa bu hatanın özel durumunu açıklar.statusgövdede bulunuyorsa HTTP durum kodunu yansıtır.instancevarsa hatanın bu oluşumunu tanımlayan bir URI’dir.errors, bu örnekte ASP.NET Core’un doğrulama yanıtına eklediği alan bazlı hata sözlüğüdür.
Örneğin bir form, errors.quantity içindeki mesajları adet alanının altında gösterebilir. Belirli bir hata türünü otomatik işlemek için çevrilebilen title veya detail metnini ayrıştırmak yerine type değerini kullanabilir.
.NET 10 ile çalıştırılabilir Minimal API örneği
Yeni bir boş web projesi oluşturun. Program.cs dosyasını örnekle değiştirip uygulamayı başlatın. Uygulama doğrulama, mevcut siparişi okuma ve beklenmeyen bir hatayı üretme yolları sunar. Sipariş verisi örnek kodun içindedir.
dotnet new web -n ProblemDetailsDemo -f net10.0
cd ProblemDetailsDemo
# Program.cs dosyasını aşağıdaki C# koduyla değiştirin.
dotnet run --no-launch-profile --urls http://localhost:5080var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();
app.MapPost("/orders/validate", IResult (OrderInput input) =>
{
if (input.Quantity < 1)
{
return Results.ValidationProblem(new Dictionary<string, string[]>
{
["quantity"] = ["Adet en az 1 olmalıdır."]
});
}
return Results.Ok(new { quantity = input.Quantity });
});
app.MapGet("/orders/{id:int}", IResult (int id) =>
{
return id == 1
? Results.Ok(new { id, quantity = 2 })
: Results.NotFound();
});
// Yalnızca örnekte 500 yanıtı üretmek için.
app.MapGet("/demo/failure", () =>
{
throw new InvalidOperationException("Örnek iç hata");
});
app.Run();
record OrderInput(int Quantity);AddProblemDetails()hata gövdelerini yazabilen servisi kaydeder.UseExceptionHandler()örnekte fırlatılan istisnayı yakalar. İstemci genel bir500yanıtı alır. İç hata metni ve stack trace sunucu tarafında kalır.UseStatusCodePages(),Results.NotFound()gibi boş gövdeli hata yanıtlarında devreye girer.Results.ValidationProblem()ise alan hatalarını içeren gövdeyi kendisi oluşturur.
400, 404 ve 500 yanıtlarını karşılaştırın
Uygulama çalışırken ikinci bir PowerShell penceresinde şu istekleri gönderin. -i ile durum satırı, başlıklar ve gövdeyi birlikte görebilirsiniz.
'{"quantity":0}' | curl.exe -sS -i --json '@-' http://localhost:5080/orders/validate
curl.exe -sS -i -H 'Accept: application/problem+json' http://localhost:5080/orders/99
curl.exe -sS -i -H 'Accept: application/problem+json' http://localhost:5080/demo/failureÖrneği ASP.NET Core 10.0.11 ile çalıştırdım. İlk isteğin yanıtı aşağıdaki gibi. Yanıtı okunur hâle getirmek için diğer başlıkları ve her istekte değişen traceId alanını çıkardım.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"quantity": ["Adet en az 1 olmalıdır."]
}
}- 400. Sıfır adet gönderen istekte
errors.quantityaltında bir mesaj gelir. İstemci kullanıcının hangi alanı düzeltmesi gerektiğini bilir. - 404. 99 numaralı sipariş için
statusdeğeri 404’tür. Bu yanıtta form alanına ait bir hata yoktur. - 500. Test rotasındaki istisna genel bir hata yanıtı üretir. Sunucu günlüğünde ise istisnanın ayrıntısı vardır.
Üç hata yanıtında da Content-Type değeri application/problem+json ile başlar. Başarılı yanıtı karşılaştırmak için ilk isteği quantity değeri 2 ile, ikinci isteği de /orders/1 adresine gönderin. Bu kez 200 ve normal JSON gövdesi alırsınız.
Bir hata gövdesi beklerken yalnızca durum kodu geliyorsa Accept başlığını da kontrol edin. İstemci yalnızca text/html istediğinde varsayılan ProblemDetails yazıcısı middleware üzerinden JSON gövdesi üretmez. API istemcisinde desteklenen JSON türünü kabul ettiğinizi belirtin.
Benzer İçerikler

Middleware Nedir? .NET Core'da Middleware Kullanımı
Middleware, yazılım geliştirme sürecinde istemci(client) ile sunucu(server) arasındaki iletişimin yönetilmesinde kullanılan en önemli bileşenlerden birisidir. Bir isteği middleware aracılığıyla değiştirebilir veya durdurabiliriz.
25 Eylül 2025
2 dakika 38 saniye okuma süresi

Fluent Validation Nedir? .NET Core’da Fluent Validation Kullanımı
Fluent validation, bir nesnenin geçerli olup olmadığını kontrol ederek ilgili nesne üzerinde doğrulama işlemlerini gerçekleştirmek amacıyla kullanılan popüler bir doğrulama kütüphanesidir. Fluent Validation, validasyon işlemlerinin basit, okunabilir ve genişletilebilir bir şekilde gerçekleştirilmesini sağlamaktadır.
17 Temmuz 2024
2 dakika 21 saniye okuma süresi