Standardize ASP.NET Core API Errors with RFC 7807

When building robust ASP.NET Core APIs, delivering consistent, machine-readable error responses is paramount for a smooth developer experience and reliable client applications. While ASP.NET Core provides built-in support for problem details, achieving strict adherence to RFC 7807, especially when needing fine-grained control over response elements or integrating with specific observability tools, often calls for a more tailored approach. This is precisely where implementing a custom IExceptionHandler shines, offering complete control over the structure and content of your error payloads.

ASP.NET Core’s default exception handling middleware generates problem details, but direct customization of crucial RFC 7807 properties like type, title, status, detail, and instance can be challenging. A custom IExceptionHandler allows you to precisely define these fields, making it ideal for scenarios where you need to integrate with existing logging frameworks like Serilog or application performance monitoring (APM) tools that expect a standardized problem details format. By intercepting exceptions and crafting your own ProblemDetails objects, you ensure every error response conforms to your API’s defined standards.

Here’s a practical implementation of a custom IExceptionHandler for ASP.NET Core 8. This example defines a handler that logs the exception details and then constructs an RFC 7807 compliant problem details response, ensuring clarity and consistency for consumers.

using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

public class Rfc7807ProblemDetailsExceptionHandler : IExceptionHandler
{
    private readonly ILogger<Rfc7807ProblemDetailsExceptionHandler> _logger;

    public Rfc7807ProblemDetailsExceptionHandler(ILogger<Rfc7807ProblemDetailsExceptionHandler> logger)
    {
        _logger = logger;
    }

    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, CancellationToken cancellationToken)
    {
        var exceptionHandlerFeature = httpContext.Features.Get<IExceptionHandlerFeature>();
        var exception = exceptionHandlerFeature?.Error;

        if (exception is not null)
        {
            _logger.LogError(exception, "Unhandled exception encountered in API endpoint.");

            // Crafting an RFC 7807 compliant ProblemDetails object
            var problemDetails = new ProblemDetails
            {
                // The 'type' member is a URI reference that identifies the problem type.
                // For RFC 7807, a common practice is to link to the specification.
                Type = "https://tools.ietf.org/html/rfc7807",
                // A short, human-readable summary of the problem.
                Title = "Internal Server Error",
                // The HTTP status code generated by the origin server.
                Status = StatusCodes.Status500InternalServerError,
                // A human-readable explanation specific to this occurrence of the problem.
                Detail = exception.Message,
                // A URI reference that identifies the specific occurrence of the problem.
                Instance = httpContext.Request.Path
            };

            // Optional: Add custom extensions for more context, e.g., trace ID
            // problemDetails.Extensions.Add("traceId", System.Diagnostics.Activity.Current?.Id ?? httpContext.TraceIdentifier);

            // Use Results.Problem() which leverages the registered ProblemDetailsFactory
            await httpContext.WriteHttpResultAsAsync(Results.Problem(problemDetails));
            return true; // Indicate that the exception has been handled
        }

        return false; // Let other handlers or default middleware process the exception
    }
}

To integrate this handler into your ASP.NET Core application, ensure you register it in your Program.cs file. Critically, you must also call builder.Services.AddProblemDetails();. This seemingly redundant step is crucial because AddProblemDetails() registers essential services, most notably the ProblemDetailsFactory, which the Results.Problem() method relies upon to correctly construct and serialize the ProblemDetails object, even when using a custom handler. Register your custom handler before other exception-handling middleware to ensure it takes precedence.

By implementing a custom IExceptionHandler, you gain the power to standardize your API’s error responses beyond the default behavior, ensuring consistent, RFC 7807 compliant outputs. This not only simplifies client integration but also enhances your API’s observability and maintainability. Trigger an unhandled exception in an endpoint after registering your custom handler to witness the RFC 7807 formatted error response in action.