Error Handling

Something will throw. A database connection will drop, a third-party call will time out, a null will appear where your code assumed an object. The question is not whether it happens but what the caller receives when it does.

Two audiences need different things from the same failure. The caller needs a correct status code and enough information to decide what to do next. You need the exception type, the message, the stack trace and the request details, so you can find the cause. Those two needs pull in opposite directions, and the whole design of error handling comes from keeping them separate.

Central handling means one place at the top of the request pipeline that catches whatever escaped, logs the full detail, and writes a deliberately plain response. Without it, error formatting is scattered across every action and each one is slightly different.

// EmployeeApiExceptionHandler.cs
public sealed class EmployeeApiExceptionHandler(
    ILogger<EmployeeApiExceptionHandler> logger) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext context,
        Exception exception,
        CancellationToken cancellationToken)
    {
        // Full detail, server side only. The exception object goes in as the
        // first argument so the logger records type, message and stack trace.
        logger.LogError(
            exception,
            "Unhandled exception for {Method} {Path}",
            context.Request.Method,
            context.Request.Path);

        (int status, string title) = exception switch
        {
            DepartmentClosedException => (StatusCodes.Status409Conflict,
                "The department is closed to new employees."),
            EmployeeNotFoundException => (StatusCodes.Status404NotFound,
                "The employee does not exist."),
            _ => (StatusCodes.Status500InternalServerError,
                "An unexpected error occurred."),
        };

        ProblemDetails problem = new()
        {
            Status = status,
            Title = title,
            Instance = context.Request.Path,
        };
        problem.Extensions["traceId"] = context.TraceIdentifier;

        context.Response.StatusCode = status;
        await context.Response.WriteAsJsonAsync(problem, cancellationToken);

        return true;
    }
}

• IExceptionHandler is the interface the built-in exception handling middleware calls. Returning true means you have written the response and the middleware should stop; returning false lets the next handler try.
• The log call happens first and receives the exception itself. That is what captures the stack trace. Everything after it is about the caller.
• The switch maps exception types to status codes in one place. Add a case when you introduce a domain exception; the default case is the catch-all 500.
• Notice what the ProblemDetails does not contain: no exception message, no type name, no stack trace. The title is a fixed string you wrote, not something derived from the failure.
• traceId goes into Extensions so it appears as an extra JSON property. It is the thread that connects this response to the log entry above.

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<EmployeeApiExceptionHandler>();
builder.Services.AddControllers();

WebApplication app = builder.Build();

if (app.Environment.IsDevelopment())
{
    // Full stack trace in the browser. Never reachable in production.
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler();
    app.UseHsts();
}

app.UseHttpsRedirection();
app.MapControllers();

app.Run();

• AddProblemDetails registers the service that produces standard problem responses, including for status codes the framework generates itself.
• AddExceptionHandler registers your handler. Register more than one if you want them tried in order; the first to return true wins.
• UseExceptionHandler adds the middleware. It goes near the top of the pipeline because it can only catch exceptions thrown by components that come after it.
• The developer exception page is genuinely useful and genuinely dangerous. It renders the exception, the stack trace, the source lines and the request headers. Keeping it inside the development branch is what stops that page ever reaching a real user.

// Response body for an unexpected failure (HTTP 500)
{
  "title": "An unexpected error occurred.",
  "status": 500,
  "instance": "/api/employees/148",
  "traceId": "00-4bd9f0c1a7e34f52-9c1f2ab7-00"
}

// The matching server log entry, structured
{
  "Timestamp": "2025-04-08T09:14:22.8410Z",
  "Level": "Error",
  "Message": "Unhandled exception for GET /api/employees/148",
  "Exception": "Npgsql.NpgsqlException: Connection refused ... at HrDbContext...",
  "TraceId": "00-4bd9f0c1a7e34f52-9c1f2ab7-00",
  "RequestPath": "/api/employees/148"
}

• The response tells the caller three things: it failed, it was not their fault, and here is a reference. That is everything a well-behaved client needs.
• The log holds the cause. The driver name, the connection failure and the code path are all present, and none of it crossed the network.
• The same traceId appears in both. That is the whole mechanism for supporting a user: they quote the identifier, you find the entry.
• Notice that the response gives away nothing about your stack, your database or your file layout. Internal detail in an error response is information about your system given to whoever asked for it.