By the end of this session, you will be able to:

• Implement a global exception handling middleware in .NET
• Return structured error responses following RFC 7807 (ProblemDetails)
• Distinguish between validation errors, business errors, and unexpected errors
• Throw domain exceptions from the service layer and handle them in one place
• Never expose internal stack traces to API consumers

Not all errors are equal. Distinguishing them lets you return the right status code and craft a response the client can act on.

Validation failures return an errors dictionary — each key is the field name, each value is an array of error messages for that field.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Title":   ["The Title field is required."],
    "DueDate": ["DueDate must be in the future."]
  }
}

public class GlobalExceptionMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<GlobalExceptionMiddleware> _logger;

    public GlobalExceptionMiddleware(RequestDelegate next,
        ILogger<GlobalExceptionMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (NotFoundException ex)
        {
            await WriteProblemDetails(context, 404, "Resource not found", ex.Message);
        }
        catch (ValidationException ex)
        {
            await WriteProblemDetails(context, 422, "Validation failed", ex.Message);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unhandled exception");
            await WriteProblemDetails(context, 500, "An unexpected error occurred.",
                "Please contact support with your traceId.");
        }
    }
}

The catch-all logs the full exception server-side but returns only a generic message to the client.

private static async Task WriteProblemDetails(
    HttpContext ctx, int status, string title, string detail)
{
    ctx.Response.StatusCode = status;
    ctx.Response.ContentType = "application/problem+json";
    var problem = new ProblemDetails
    {
        Status = status,
        Title  = title,
        Detail = detail
    };
    await ctx.Response.WriteAsJsonAsync(problem);
}

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
        {
            var errors = context.ModelState
                .Where(e => e.Value?.Errors.Count > 0)
                .ToDictionary(
                    k => k.Key,
                    v => v.Value!.Errors.Select(e => e.ErrorMessage).ToArray()
                );

            var problem = new ValidationProblemDetails(errors)
            {
                Status = 400,
                Title  = "One or more validation errors occurred."
            };
            return new BadRequestObjectResult(problem);
        };
    });

The factory runs before your controller action is invoked — invalid models never reach your code.

Starting from the Task API built in Session 03, add structured error handling:

• Never expose stack traces to clients — log them server-side only using ILogger
• Three error categories — validation (400), business rule violations (422), and unexpected failures (500) require different status codes and handling
• ProblemDetails (RFC 7807) is the standard JSON shape for error responses — ASP.NET Core supports it out of the box
• One exception handler to rule them all — GlobalExceptionMiddleware keeps every controller free of try-catch blocks
• Throw from the service, handle in middleware — domain exceptions are a first-class communication mechanism, not a last resort
• traceId in the response lets clients report errors that you can correlate with server logs without leaking implementation details

Session 06 — API Versioning

• Now that your API returns consistent, structured responses, Session 06 covers how to evolve that API without breaking existing clients
• You will implement URL-based and header-based versioning using the Asp.Versioning NuGet package
• We will look at how versioning and error handling interact — what happens when a client calls a deprecated or removed version
• After Session 06, your Task API will support multiple coexisting versions that can evolve independently

Extend your Task API with global error handling and structured ProblemDetails responses.

What to build:

• Create a NotFoundException class and wire it to a 404 response in GlobalExceptionMiddleware
• Create a ConflictException class and throw it from TaskService.Create if a task with the same title already exists — wire it to 409
• Register the middleware in Program.cs as the first item in the pipeline
• Remove all try-catch blocks from your controller — let the middleware handle them

Acceptance criteria:

• GET /api/tasks/999 returns 404 with a valid ProblemDetails JSON body
• POST /api/tasks with a duplicate title returns 409 with a ProblemDetails body
• An unhandled Exception returns 500 with a generic message — no stack trace in the response
• All error responses use Content-Type: application/problem+json