Atya.Errors.ProblemDetails 1.0.0

Atya.Errors.ProblemDetails

Atya.Errors.ProblemDetails adds RFC 9457-style ASP.NET Core problem details responses for the exception types in Atya.Errors.Exceptions.

It is intended for API boundaries where production services need consistent HTTP status codes, stable problem type identifiers, trace/correlation metadata, and safe handling of unexpected exceptions.

Install

dotnet add package Atya.Errors.ProblemDetails

Compatibility

• Targets net10.0.
• Requires ASP.NET Core through the Microsoft.AspNetCore.App framework reference.
• Depends on Atya.Errors.Exceptions and Atya.Foundation.Guards.

Quick Start

Register the services and add the exception handler middleware early in the pipeline.

using Atya.Errors.ProblemDetails.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAtyaProblemDetails();

var app = builder.Build();

app.UseAtyaProblemDetails();

app.MapGet("/customers/{id}", (Guid id) =>
{
    throw new Atya.Errors.Exceptions.NotFoundException(
        $"Customer '{id}' was not found.",
        "customers.not_found");
});

app.Run();

The response is written as application/problem+json and includes the standard problem details members plus Atya extension members when available.

{
  "type": "urn:atya:problem-type:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Customer '...' was not found.",
  "instance": "/customers/...",
  "traceId": "...",
  "errorCode": "customers.not_found"
}

Default Mappings

Derived exception types use the first assignable mapping when an exact mapping is not configured.

Extension Members

Validation errors use this shape:

{
  "propertyName": "Email",
  "message": "Email is required.",
  "errorCode": "validation.required"
}

Attempted values are omitted by default because they can contain sensitive user input.

Configuration

builder.Services.AddAtyaProblemDetails(options =>
{
    options.IncludeExceptionMetadata = true;
    options.IncludeTraceId = true;
    options.IncludeValidationAttemptedValues = false;

    options.CorrelationIdAccessor = httpContext =>
        httpContext.Request.Headers.TryGetValue("X-Request-ID", out var values)
            ? values.ToString()
            : null;

    options.Map<TimeoutException>(
        StatusCodes.Status504GatewayTimeout,
        "Gateway Timeout",
        "urn:atya:problem-type:gateway-timeout",
        static (_, _) => "The upstream service did not respond in time.");

    options.ExtensionNames.Errors = "validationErrors";
    options.ExtensionNames.Metadata = null;

    options.CustomizeProblemDetails = (httpContext, exception, problemDetails) =>
    {
        problemDetails.Extensions["service"] = "orders-api";
    };
});

Map<TException> replaces an existing mapping for the same exception type, trims the title and type values, and rejects HTTP status codes outside the standard 100 through 599 range. RemoveMapping<TException>() removes one mapping, and ClearMappings() lets a service fully own its public error contract.

Exception Details

Unhandled exceptions and mapped 500-level exceptions are deliberately sanitized by default:

{
  "status": 500,
  "title": "Internal Server Error",
  "detail": "An unexpected error occurred."
}

Only enable raw exception details for trusted environments.

builder.Services.AddAtyaProblemDetails(options =>
{
    options.IncludeExceptionDetailsPredicate = (httpContext, exception) =>
        builder.Environment.IsDevelopment();
});

Known Atya exceptions below status 500 use their exception message as detail. For mapped 500-level exceptions, use a safe Map<TException> detail factory when a public detail is useful.

Versioning

Stable packages use SemVer and are produced from vMAJOR.MINOR.PATCH tags. Problem type URIs, extension names, public types, and serialized JSON member names are treated as compatibility contracts.

Support

Report issues through the repository at https://github.com/AtyaLibraries/ProblemDetails. Include the package version, target framework, ASP.NET Core version, and a minimal reproduction whenever possible.