Standardize API Error Responses with RFC 7807 in ASP.NET Core

Inconsistent API error responses are a significant headache for developers integrating with your services. Clients often waste valuable time debugging and adapting to wildly different error formats, leading to increased development friction and potential bugs. ASP.NET Core 8, however, offers a standardized solution: RFC 7807 Problem Details. While the framework provides sensible defaults, you’ll frequently need to tailor this to include application-specific context or map your custom exception types to the RFC 7807 standard.

To achieve this customization, you can implement IExceptionHandler. This interface allows you to intercept unhandled exceptions and format them as RFC 7807 Problem Details. Within the TryHandleAsync method, you can inspect the caught exception, extract pertinent information, and construct a ProblemDetails object. Crucially, you’ll register your custom handler in Program.cs using builder.Services.AddExceptionHandler<T>() and then app.UseExceptionHandler() to ensure your specialized logic executes before the framework’s default handling. This approach provides granular control over your API’s error reporting.

A common and powerful use case is mapping your application-specific exceptions to standardized Problem Details. For example, a UserNotFoundException could be mapped to a 404 Not Found status code, with a descriptive title, detail, and a unique instance URI pointing to the problematic request. The AddExceptionHandler mechanism, coupled with the WriteProblemDetailsAsync extension method, makes this straightforward. Remember that the order of registration for multiple exception handlers matters; more specific handlers should typically precede broader ones.

A critical consideration is robustness: your custom handler must gracefully handle cases where the exception is null or if constructing the ProblemDetails object fails. Furthermore, be extremely cautious about leaking sensitive internal application details in your error responses; always sanitize exception messages before exposing them to clients. For more intricate error scenarios, leveraging the IProblemDetailsService can significantly simplify populating the ProblemDetails object with contextual information, such as request details and type identifiers.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails(); // Essential for RFC 7807 support
builder.Services.AddExceptionHandler<CustomExceptionHandler>(); // Register your custom handler

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UseExceptionHandler(); // Registers the configured exception handlers

app.MapGet("/users/{id}", (int id) =>
{
    if (id == 123)
    {
        throw new UserNotFoundException($"User with ID {id} not found.");
    }
    return Results.Ok($"User details for {id}");
});

app.Run();

// CustomExceptionHandler.cs
using Microsoft.AspNetCore.Diagnostics;
using Microsoft.AspNetCore.Mvc;

public class CustomExceptionHandler : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception)
    {
        if (exception is UserNotFoundException)
        {
            var problemDetails = new ProblemDetails
            {
                Status = StatusCodes.Status404NotFound,
                Title = "Resource Not Found",
                Detail = exception.Message,
                Instance = httpContext.Request.Path,
                Type = "https://example.com/api/errors/user-not-found" // Custom type URI
            };

            await httpContext.WriteProblemDetailsAsync(problemDetails);
            return true; // Exception handled
        }

        // Allow the default handler or other registered handlers to process
        return false;
    }
}

public class UserNotFoundException : Exception
{
    public UserNotFoundException(string message) : base(message) { }
}