error-handling

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