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.

Can Yüksel

Erdoğancan Yüksel

20 Kasım 2026

1 dakika 38 saniye okuma süresi

ProblemDetails biçiminde 400, 404 ve 500 API hata yanıtları

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?

  • type problem türünü tanımlayan bir URI’dir. İstemcinin belirli bir hata için farklı davranması gerekiyorsa belgelenmiş bir türü tanıyabilir.
  • title problem türünün kısa açıklamasıdır. detail varsa bu hatanın özel durumunu açıklar.
  • status gövdede bulunuyorsa HTTP durum kodunu yansıtır. instance varsa 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:5080
var 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 bir 500 yanı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.quantity altında bir mesaj gelir. İstemci kullanıcının hangi alanı düzeltmesi gerektiğini bilir.
  • 404. 99 numaralı sipariş için status değ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