Global Exception Handling & Middleware

app.UseExceptionHandler("/error");  // catches any unhandled exception from everything after this line

app.Map("/error", (HttpContext context) => {
    return Results.Problem(title: "An error occurred", statusCode: 500);
});

Common follow-ups: How does UseExceptionHandler differ from the newer IExceptionHandler interface in .NET 8?;What information should and shouldn't be included in an error response for security reasons?

public class ValidationExceptionHandler : IExceptionHandler {
    public async ValueTask<bool> TryHandleAsync(HttpContext context, Exception exception, CancellationToken ct) {
        if (exception is not ValidationException ve) return false;  // not handled, try next handler
        context.Response.StatusCode = 400;
        await context.Response.WriteAsJsonAsync(new { errors = ve.Errors }, ct);
        return true;
    }
}

builder.Services.AddExceptionHandler<ValidationExceptionHandler>();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();  // fallback

Common follow-ups: What determines the order multiple registered IExceptionHandlers are tried in?;How does this integrate with ProblemDetails for standardized error responses?

builder.Services.AddProblemDetails();  // enables automatic ProblemDetails for errors

app.UseExceptionHandler();  // now produces RFC-compliant ProblemDetails responses automatically

// Manual usage:
return Results.Problem(title: "Insufficient stock", statusCode: 409, detail: "Only 2 units remaining");

Common follow-ups: What are the standard vs extension members of the ProblemDetails format?;How do you add custom extension fields to a ProblemDetails response?

public class GlobalExceptionHandler : IExceptionHandler {
    public async ValueTask<bool> TryHandleAsync(HttpContext context, Exception exception, CancellationToken ct) {
        var (statusCode, title) = exception switch {
            NotFoundException => (404, "Resource not found"),
            ValidationException => (400, "Validation failed"),
            UnauthorizedAccessException => (403, "Access denied"),
            _ => (500, "An unexpected error occurred")
        };
        context.Response.StatusCode = statusCode;
        await context.Response.WriteAsJsonAsync(new { title }, ct);
        return true;
    }
}

Common follow-ups: What custom exception hierarchy design makes this mapping cleanest to maintain?;Should business logic ever throw exceptions for expected failure cases, or use a Result pattern instead?

public async ValueTask<bool> TryHandleAsync(HttpContext context, Exception exception, CancellationToken ct) {
    var traceId = context.TraceIdentifier;
    _logger.LogError(exception, "Unhandled exception. TraceId: {TraceId}", traceId);  // full details logged

    await context.Response.WriteAsJsonAsync(new {
        title = "An unexpected error occurred",  // safe, generic message to client
        traceId  // lets support correlate with server-side logs without exposing internals
    }, ct);
    return true;
}

Common follow-ups: How does a correlation/trace ID help support teams without exposing sensitive data?;What's the risk specifically of exposing stack traces regarding internal architecture?

app.MapGet("/products/{id}", (int id, IProductService service) => {
    var product = service.GetById(id) ?? throw new NotFoundException($"Product {id} not found");
    return Results.Ok(product);
});
// Relies on global UseExceptionHandler/IExceptionHandler to catch NotFoundException
// and convert it to a proper 404 response, since there's no MVC filter pipeline here

Common follow-ups: How do endpoint filters provide finer-grained exception handling than the global handler?;What's the migration path for exception filter logic when moving from MVC controllers to minimal APIs?

public class ExceptionEnrichmentMiddleware {
    private readonly RequestDelegate _next;
    public async Task InvokeAsync(HttpContext context) {
        try {
            await _next(context);
        } catch (Exception ex) {
            ex.Data["RequestPath"] = context.Request.Path;
            ex.Data["UserId"] = context.User?.Identity?.Name;
            throw;  // re-throw for the actual exception handler to process
        }
    }
}

Common follow-ups: Why is it important to re-throw rather than swallow the exception in this pattern?;How does this compare to just adding this context directly inside a single IExceptionHandler?

// Global middleware handles the general case -- no try/catch needed here
[HttpGet("{id}")]
public IActionResult GetProduct(int id) {
    var product = _service.GetById(id) ?? throw new NotFoundException();
    return Ok(product);
}

// Local try/catch for action-specific recovery logic
[HttpPost("import")]
public async Task<IActionResult> ImportProducts(IFormFile file) {
    try {
        await _importer.ImportAsync(file);
        return Ok();
    } catch (InvalidFileFormatException ex) {
        return BadRequest(new { ex.Message, SupportedFormats = new[] { "csv", "xlsx" } });  // action-specific response
    }
}

Common follow-ups: When does local try/catch handling risk creating inconsistent error response formats?;How do you decide which exceptions deserve action-specific handling versus the global default?

[ApiController]  // enables automatic model validation short-circuiting
public class ProductsController : ControllerBase {
    [HttpPost]
    public IActionResult Create([Required] ProductDto dto) {
        // If dto fails validation, this method body never executes --
        // [ApiController] already returned a 400 ValidationProblemDetails automatically
        return Ok();
    }
}

Common follow-ups: How do you customize the automatic validation error response format via InvalidModelStateResponseFactory?;How would you unify both paths to guarantee identical response shapes?

public class ApiException : Exception {
    public int StatusCode { get; }
    public ApiException(string message, int statusCode = 400) : base(message) => StatusCode = statusCode;
}

// In the handler:
var (status, message) = exception is ApiException apiEx
    ? (apiEx.StatusCode, apiEx.Message)  // safe, intentionally client-facing
    : (500, "An unexpected error occurred");  // generic for anything else

Common follow-ups: How do you ensure developers consistently use the ApiException base class for new user-facing errors?;What's the risk of accidentally making ApiException too broadly applicable?