Global Exception Handling in ASP.NET Core

In ASP.NET Core, individual controller actions should not contain try/catch blocks for domain errors — that responsibility belongs to a centralised exception handler. A well-designed exception handling pipeline ensures that every unhandled exception is caught, logged, and converted to a structured HTTP response with the correct status code and a consistent ProblemDetails body. This keeps controllers thin, eliminates repetition, and gives you one place to tune error response formatting for your entire API.

ProblemDetails — RFC 9457 Error Responses #

// ProblemDetails is the .NET implementation of RFC 9457 (Problem Details for HTTP APIs)
// Standard error response shape:
// {
//   "type":   "https://tools.ietf.org/html/rfc9110#section-15.5.5",
//   "title":  "Not Found",
//   "status": 404,
//   "detail": "Post '42' was not found.",
//   "instance": "/api/posts/42",
//   "traceId": "00-abc123-01"
// }

// Enable ProblemDetails in Program.cs
builder.Services.AddProblemDetails();   // enables built-in ProblemDetails support
// ASP.NET Core 8 also enables it for unhandled exceptions automatically

Global Exception Handler — .NET 8 IExceptionHandler #

// ── IExceptionHandler — the clean .NET 8 approach ────────────────────────
public class GlobalExceptionHandler : IExceptionHandler
{
    private readonly ILogger<GlobalExceptionHandler> _logger;

    public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
        => _logger = logger;

    public async ValueTask<bool> TryHandleAsync(
        HttpContext        httpContext,
        Exception          exception,
        CancellationToken  cancellationToken)
    {
        _logger.LogError(exception,
            "Unhandled exception: {Message}", exception.Message);

        var (statusCode, title) = exception switch
        {
            NotFoundException     => (StatusCodes.Status404NotFound,    "Not Found"),
            ConflictException     => (StatusCodes.Status409Conflict,    "Conflict"),
            ValidationException   => (StatusCodes.Status422UnprocessableEntity, "Validation Error"),
            ForbiddenException    => (StatusCodes.Status403Forbidden,   "Forbidden"),
            AppException          => (StatusCodes.Status400BadRequest,  "Bad Request"),
            _                     => (StatusCodes.Status500InternalServerError, "Internal Server Error"),
        };

        var problemDetails = new ProblemDetails
        {
            Status   = statusCode,
            Title    = title,
            Detail   = exception is AppException
                           ? exception.Message
                           : "An unexpected error occurred.",
            Instance = httpContext.Request.Path,
        };

        // Add structured error details for ValidationException
        if (exception is ValidationException validationEx)
            problemDetails.Extensions["errors"] = validationEx.Errors;

        // Add trace ID for log correlation
        problemDetails.Extensions["traceId"] =
            System.Diagnostics.Activity.Current?.Id ?? httpContext.TraceIdentifier;

        httpContext.Response.StatusCode  = statusCode;
        httpContext.Response.ContentType = "application/problem+json";
        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);

        return true;   // true = exception handled; false = let next handler try
    }
}

// ── Registration in Program.cs ────────────────────────────────────────────
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// ...

app.UseExceptionHandler();   // activates the IExceptionHandler pipeline

Controller Action — No Try/Catch Needed #

[ApiController]
[Route("api/posts")]
public class PostsController : ControllerBase
{
    private readonly IPostService _service;
    public PostsController(IPostService service) => _service = service;

    [HttpGet("{id:int}")]
    public async Task<IActionResult> GetById(int id)
    {
        // No try/catch — NotFoundException propagates to GlobalExceptionHandler
        var post = await _service.GetByIdAsync(id);
        return Ok(post);
    }

    [HttpPost("{id:int}/publish")]
    public async Task<IActionResult> Publish(int id)
    {
        // No try/catch — NotFoundException, ConflictException, ForbiddenException
        // are all handled globally and converted to the correct HTTP status
        var published = await _service.PublishAsync(id, User.GetUserId());
        return Ok(published);
    }
}
// Result: clean, thin controllers with zero exception handling boilerplate

Common Mistakes #

Mistake 1 — Try/catch in every controller action #

❌ Wrong — repetitive, error-prone, hard to maintain consistently:

public async Task<IActionResult> GetById(int id)
{
    try { return Ok(await _service.GetById(id)); }
    catch (NotFoundException) { return NotFound(); }
    catch (Exception) { return StatusCode(500); }
}

✅ Correct — register GlobalExceptionHandler once; controllers stay clean.

Mistake 2 — Returning stack traces in production error responses #

❌ Wrong — exposes internal implementation details and potential security vulnerabilities.

✅ Correct — use generic messages in production; reserve detailed errors for development environment only.