Error Handling Patterns

This skill owns the Result<TValue, TError> definition. ddd, clean-architecture and vertical-slice use it and do not redefine it.

Philosophy: When to Use Results vs Exceptions

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

Result Type

Define once in the Domain project (e.g. Domain/Common/Result.cs). It has no dependencies, so every layer can reference it:

namespace MyApp.Domain.Common;

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

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

    public TValue Value => IsSuccess ? _value! : throw new InvalidOperationException("Result is a failure; read Error.");
    public TError Error => IsFailure ? _error! : throw new InvalidOperationException("Result is a success; read Value.");

    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 static implicit operator Result<TValue, TError>(TValue value) => Success(value);
    public static implicit operator Result<TValue, TError>(TError error) => Failure(error);

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

// Success marker for operations that return no value: Result<Done, TError>.
public readonly record struct Done
{
    public static readonly Done Value = default;
}

Gotchas:

• default(Result<,>), including an uninitialised field of this type, is a failure with a null Error. Always construct one through Success/Failure or the implicit conversions.
• The implicit conversions let a method return order; or return new NotFoundError(...). They become ambiguous when TValue and TError are the same type or related by inheritance, and C# applies no user-defined conversion from an interface-typed value. Call Success/Failure explicitly in those cases.
• The no-value form is named Done, not Unit (clashes with MediatR.Unit) or Ok (clashes with Microsoft.AspNetCore.Http.HttpResults.Ok).
• A discarded Result compiles silently. Treat one as a bug in review.

Typed Error Records

namespace MyApp.Domain.Errors;

public abstract record DomainError(string Message);

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

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

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

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

Returning Results

The aggregate owns the business rule and returns a result. The service propagates it rather than re-checking state:

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

        var cancelled = order.Cancel(clock);     // Result<Done, DomainError>
        if (cancelled.IsFailure)
            return cancelled.Error;

        await repo.SaveChangesAsync(ct);
        return order;
    }
}

Mapping Results to HTTP (Minimal API)

app.MapPost("/orders/{id:guid}/cancel", async (Guid id, OrderService svc, CancellationToken ct) =>
{
    var result = await svc.CancelAsync(id, ct);
    return result.Match<IResult>(order => TypedResults.Ok(order), MapError);
});

static IResult MapError(DomainError error) => error switch
{
    NotFoundError e   => TypedResults.Problem(e.Message, statusCode: StatusCodes.Status404NotFound),
    ConflictError e   => TypedResults.Problem(e.Message, statusCode: StatusCodes.Status409Conflict),
    ForbiddenError e  => TypedResults.Problem(e.Message, statusCode: StatusCodes.Status403Forbidden),
    ValidationError e => TypedResults.ValidationProblem(
        new Dictionary<string, string[]> { [e.Field] = [e.Reason] }),
    _                 => TypedResults.Problem(error.Message, statusCode: StatusCodes.Status500InternalServerError)
};

• A domain ForbiddenError maps to a 403 problem, not TypedResults.Forbid(). Forbid() runs the authentication handler's forbid flow, which for cookie auth redirects to an access-denied page.
• Leave type unset. AddProblemDetails() fills type and title with the RFC 9110 section URI for the status code (e.g. 404 → https://tools.ietf.org/html/rfc9110#section-15.5.5).
• Returning IResult loses OpenAPI response metadata. Declare .ProducesProblem(404) and so on for the endpoint, or return a Results<Ok<T>, ProblemHttpResult, ...> union.

Controller mapping: references/controllers-and-jobs.md.

ProblemDetails (RFC 9457)

RFC 9457 obsoletes RFC 7807. The JSON shape is unchanged.

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;
    };
});

Global Exception Handler

Catches unhandled exceptions at the HTTP boundary. Writing through IProblemDetailsService keeps the CustomizeProblemDetails callback (traceId, instance) in the response:

public sealed class GlobalExceptionHandler(
    IProblemDetailsService problemDetails,
    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);

        ctx.Response.StatusCode = StatusCodes.Status500InternalServerError;
        return await problemDetails.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = ctx,
            Exception = exception,
            ProblemDetails = { Title = "An unexpected error occurred." }
        });
    }
}

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

app.UseExceptionHandler();   // first in the pipeline, before routing

Never put exception.Message or the stack trace in detail, because it reaches the client.

Background-job exception boundaries: references/controllers-and-jobs.md.

Do / Don't

See Also

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