error-handling

name	error-handling
description	Result pattern, ProblemDetails (RFC 7807), global exception boundaries, and typed error records for .NET APIs.

Error Handling Patterns

Reference for structured error handling in .NET APIs. Used by dnp-planner, dnp-api-scaffolder, and dnp-tdd-developer-hard.

Philosophy: When to Use Results vs Exceptions

Scenario	Approach
Domain rule violation (not found, invalid state, business constraint)	Result<TValue, TError> — expected failure path
Infrastructure failure (DB timeout, network error, config missing)	Exception — unexpected, unrecoverable at call site
Validation failure (bad input from HTTP layer)	ValidationProblemDetails via model binding / FluentValidation
Unhandled exception escaping to HTTP	GlobalExceptionHandler → 500 ProblemDetails

Never throw exceptions for expected domain outcomes. Never swallow exceptions at call sites.

Result Type

Define in a shared location (e.g., Common/Result.cs):

namespace MyApp.Common;

public readonly record struct Result<TValue, TError>
{
    private readonly TValue? _value;
    private readonly TError? _error;

    public bool IsSuccess { get; }
    public bool IsFailure => !IsSuccess;

    private Result(TValue value) { _value = value; IsSuccess = true; }
    private Result(TError error) { _error = error; IsSuccess = false; }

    public static Result<TValue, TError> Success(TValue value) => new(value);
    public static Result<TValue, TError> Failure(TError error) => new(error);

    public TResult Match<TResult>(
        Func<TValue, TResult> onSuccess,
        Func<TError, TResult> onFailure)
        => IsSuccess ? onSuccess(_value!) : onFailure(_error!);

    public void Match(Action<TValue> onSuccess, Action<TError> onFailure)
    {
        if (IsSuccess) onSuccess(_value!);
        else onFailure(_error!);
    }
}

Typed Error Records

Define errors as discriminated records in the domain layer:

namespace MyApp.Domain.Errors;

public abstract record DomainError(string Message);

public record NotFoundError(string Resource, object Id)
    : DomainError($"{Resource} with id '{Id}' was not found.");

public record ConflictError(string Resource, string Reason)
    : DomainError($"{Resource} conflict: {Reason}");

public record ValidationError(string Field, string Reason)
    : DomainError($"Validation failed for '{Field}': {Reason}");

public record ForbiddenError(string Action, string Resource)
    : DomainError($"Not permitted to {Action} {Resource}.");

Domain Service — Returning Results

public class OrderService(IOrderRepository repo, ILogger<OrderService> logger)
{
    public async Task<Result<Order, DomainError>> GetByIdAsync(int id, CancellationToken ct)
    {
        var order = await repo.GetByIdAsync(id, ct);
        if (order is null)
            return Result<Order, DomainError>.Failure(new NotFoundError("Order", id));

        return Result<Order, DomainError>.Success(order);
    }

    public async Task<Result<Order, DomainError>> CancelAsync(int id, CancellationToken ct)
    {
        var order = await repo.GetByIdAsync(id, ct);
        if (order is null)
            return Result<Order, DomainError>.Failure(new NotFoundError("Order", id));

        if (order.Status == "Shipped")
            return Result<Order, DomainError>.Failure(
                new ConflictError("Order", "cannot cancel a shipped order"));

        order.Cancel();
        await repo.SaveChangesAsync(ct);
        return Result<Order, DomainError>.Success(order);
    }
}

Mapping Results to HTTP (Minimal API)

app.MapGet("/orders/{id}", async (int id, OrderService svc, CancellationToken ct) =>
{
    var result = await svc.GetByIdAsync(id, ct);
    return result.Match(
        order => TypedResults.Ok(order),
        error => MapError(error));
});

app.MapDelete("/orders/{id}/cancel", async (int id, OrderService svc, CancellationToken ct) =>
{
    var result = await svc.CancelAsync(id, ct);
    return result.Match(
        order => TypedResults.Ok(order),
        error => MapError(error));
});

static IResult MapError(DomainError error) => error switch
{
    NotFoundError e  => TypedResults.NotFound(new { e.Message }),
    ConflictError e  => TypedResults.Conflict(new { e.Message }),
    ForbiddenError e => TypedResults.Forbid(),
    ValidationError e => TypedResults.ValidationProblem(
        new Dictionary<string, string[]> { [e.Field] = [e.Reason] }),
    _ => TypedResults.Problem(error.Message, statusCode: 500)
};

Mapping Results to HTTP (Controller)

[ApiController]
[Route("api/[controller]")]
public class OrdersController(OrderService svc) : ControllerBase
{
    [HttpGet("{id}")]
    public async Task<IActionResult> GetById(int id, CancellationToken ct)
    {
        var result = await svc.GetByIdAsync(id, ct);
        return result.Match<IActionResult>(
            order => Ok(order),
            error => error switch
            {
                NotFoundError  => NotFound(new { error.Message }),
                ForbiddenError => Forbid(),
                _              => Problem(error.Message)
            });
    }
}

ProblemDetails (RFC 7807)

ASP.NET Core returns ProblemDetails for 4xx/5xx by default when AddProblemDetails() is configured.

builder.Services.AddProblemDetails(options =>
{
    options.CustomizeProblemDetails = ctx =>
    {
        ctx.ProblemDetails.Instance =
            $"{ctx.HttpContext.Request.Method} {ctx.HttpContext.Request.Path}";
        ctx.ProblemDetails.Extensions["traceId"] =
            Activity.Current?.Id ?? ctx.HttpContext.TraceIdentifier;
    };
});

Standard fields:

Field	Description	Example
status	HTTP status code	404
title	Short human-readable summary	"Not Found"
type	URI identifying the problem type	"https://tools.ietf.org/html/rfc7231#section-6.5.4"
detail	Specific explanation for this occurrence	"Order 42 was not found."
instance	URI of the specific request	"GET /orders/42"

Global Exception Handler

Catches unhandled exceptions at the HTTP boundary. Infrastructure failures (DB, external services) bubble up here.

public class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
    : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext ctx,
        Exception exception,
        CancellationToken ct)
    {
        logger.LogError(exception,
            "Unhandled exception on {Method} {Path}",
            ctx.Request.Method,
            ctx.Request.Path);

        var problem = new ProblemDetails
        {
            Status = StatusCodes.Status500InternalServerError,
            Title = "An unexpected error occurred.",
            Type = "https://tools.ietf.org/html/rfc7231#section-6.6.1",
            Instance = $"{ctx.Request.Method} {ctx.Request.Path}"
        };

        ctx.Response.StatusCode = problem.Status.Value;
        await ctx.Response.WriteAsJsonAsync(problem, ct);
        return true;
    }
}

Registration:

builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
builder.Services.AddProblemDetails();

// In pipeline (before routing):
app.UseExceptionHandler();

Exception Boundaries

Only catch exceptions at:

1. HTTP layer — GlobalExceptionHandler (unhandled infrastructure failures)
2. Background job entry points — IHostedService.ExecuteAsync, Hangfire job methods

// Background job boundary
public class OrderSyncJob(OrderSyncService svc, ILogger<OrderSyncJob> logger)
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            try
            {
                await svc.SyncPendingOrdersAsync(ct);
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                logger.LogError(ex, "Order sync failed — retrying in 60s");
                await Task.Delay(TimeSpan.FromSeconds(60), ct);
            }
        }
    }
}

Do / Don't

Do	Don't
Return Result<TValue, TError> for domain failures	Throw DomainException for expected failure paths
Define typed error records per domain concept	Use stringly-typed error messages
Catch exceptions only at HTTP/job boundaries	Catch Exception at the service or repository layer
Log at the boundary with full exception	Log the same exception multiple times as it propagates
Set ClockSkew = TimeSpan.Zero on JWT validation	Let expired tokens succeed within the default 5-minute window
Use TypedResults (compile-time checked) over Results	Mix IActionResult and IResult in the same endpoint
Include traceId in ProblemDetails extensions	Expose stack traces or internal exception messages to clients

See Also

• skills/modern-csharp/SKILL.md — record types and pattern matching used in error types
• skills/aspnet-api-patterns/SKILL.md — endpoint conventions that consume these patterns