plan-forge errorhandling.instructions.md

Error Handling Patterns (.NET)

Exception Hierarchy

Define a base exception and derive specific types:

public abstract class AppException : Exception
{
    public string Code { get; }
    public int StatusCode { get; }
    
    protected AppException(string message, string code, int statusCode)
        : base(message) { Code = code; StatusCode = statusCode; }
}

public class NotFoundException : AppException
{
    public NotFoundException(string entity, string id)
        : base($"{entity} with ID '{id}' not found", "NOT_FOUND", 404) { }
}

public class ValidationException : AppException
{
    public IDictionary<string, string[]> Errors { get; }
    
    public ValidationException(IDictionary<string, string[]> errors)
        : base("Validation failed", "VALIDATION_ERROR", 400) { Errors = errors; }
}

public class ConflictException : AppException
{
    public ConflictException(string message)
        : base(message, "CONFLICT", 409) { }
}

public class ForbiddenException : AppException
{
    public ForbiddenException(string message = "Access denied")
        : base(message, "FORBIDDEN", 403) { }
}

Global Exception Middleware

Map exceptions to RFC 9457 ProblemDetails:

public class GlobalExceptionMiddleware(RequestDelegate next, ILogger<GlobalExceptionMiddleware> logger)
{
    public async Task InvokeAsync(HttpContext context)
    {
        try { await next(context); }
        catch (AppException ex)
        {
            logger.LogWarning(ex, "Application error: {Code}", ex.Code);
            await WriteProblemDetailsAsync(context, ex.StatusCode, ex.Code, ex.Message);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled exception");
            await WriteProblemDetailsAsync(context, 500, "INTERNAL_ERROR", "An unexpected error occurred");
        }
    }
}

Rules

• NEVER use empty catch blocks — always log with context
• NEVER leak stack traces to clients in production
• ALWAYS use typed exceptions — no bare throw new Exception()
• ALWAYS return ProblemDetails (RFC 9457) from API endpoints
• ALWAYS include correlation IDs in error responses
• Service layer throws typed exceptions; controllers map to HTTP status codes
• Log at Warning for client errors (4xx), Error for server errors (5xx)