ErrorLens.ErrorHandling 1.1.0

ErrorLens.ErrorHandling

Automatic, consistent error handling for ASP.NET Core APIs. Transform unhandled exceptions into structured JSON responses with zero configuration — or customize everything via attributes, configuration files, and custom handlers.

Features

• Zero-Config Exception Handling — Unhandled exceptions return structured JSON error responses out of the box
• Validation Error Details — Field-level errors with property names, messages, and rejected values
• Custom JSON Field Names — Rename any response field (code → type, message → detail, etc.)
• YAML & JSON Configuration — Configure error codes, messages, HTTP statuses via appsettings.json or errorhandling.yml
• Custom Exception Attributes — [ResponseErrorCode], [ResponseStatus], [ResponseErrorProperty]
• Custom Exception Handlers — Register IApiExceptionHandler implementations with priority ordering
• Response Customization — Add global properties (traceId, timestamp) via IApiErrorResponseCustomizer
• RFC 9457 Problem Details — Opt-in application/problem+json compliant responses
• Configurable Logging — Control log levels and stack trace verbosity per HTTP status code
• Multi-Target Support — .NET 6.0, 7.0, 8.0, 9.0, and 10.0

Installation

dotnet add package ErrorLens.ErrorHandling

Quick Start

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddErrorHandling();

var app = builder.Build();
app.UseErrorHandling();
app.MapControllers();
app.Run();

All unhandled exceptions now return structured JSON:

{
  "code": "INVALID_OPERATION",
  "message": "The operation is not valid."
}

Configuration

JSON (appsettings.json)

{
  "ErrorHandling": {
    "Enabled": true,
    "HttpStatusInJsonResponse": true,
    "DefaultErrorCodeStrategy": "AllCaps",
    "AddPathToError": true,
    "OverrideModelStateValidation": true,
    "SearchSuperClassHierarchy": true,
    "ExceptionLogging": "WithStacktrace",

    "JsonFieldNames": {
      "Code": "type",
      "Message": "detail"
    },

    "HttpStatuses": {
      "MyApp.UserNotFoundException": 404,
      "MyApp.DuplicateEmailException": 409
    },

    "Codes": {
      "MyApp.UserNotFoundException": "USER_NOT_FOUND",
      "email.Required": "EMAIL_REQUIRED"
    },

    "Messages": {
      "MyApp.UserNotFoundException": "The requested user was not found"
    },

    "LogLevels": {
      "4xx": "Warning",
      "5xx": "Error",
      "404": "Debug"
    }
  }
}

YAML (errorhandling.yml)

ErrorHandling:
  Enabled: true
  HttpStatusInJsonResponse: true
  DefaultErrorCodeStrategy: AllCaps
  AddPathToError: true
  OverrideModelStateValidation: true
  SearchSuperClassHierarchy: true
  ExceptionLogging: WithStacktrace

  JsonFieldNames:
    Code: type
    Message: detail

  HttpStatuses:
    MyApp.UserNotFoundException: 404
    MyApp.DuplicateEmailException: 409

  Codes:
    MyApp.UserNotFoundException: USER_NOT_FOUND
    email.Required: EMAIL_REQUIRED

  Messages:
    MyApp.UserNotFoundException: The requested user was not found

  LogLevels:
    4xx: Warning
    5xx: Error
    404: Debug

To use YAML configuration:

builder.Configuration.AddYamlErrorHandling("errorhandling.yml");
builder.Services.AddErrorHandling(builder.Configuration);

A full YAML template with all options is available at docs/errorhandling-template.yml.

Custom JSON Field Names

Rename any JSON property in error responses to match your API conventions:

ErrorHandling:
  JsonFieldNames:
    Code: type            # "code" → "type"
    Message: detail       # "message" → "detail"
    Status: statusCode    # "status" → "statusCode"
    FieldErrors: fields   # "fieldErrors" → "fields"
    Property: field       # "property" → "field"

Before:

{ "code": "USER_NOT_FOUND", "message": "User not found" }

After:

{ "type": "USER_NOT_FOUND", "detail": "User not found" }

Custom Exception Attributes

Decorate exception classes with attributes to control error responses:

[ResponseErrorCode("USER_NOT_FOUND")]
[ResponseStatus(HttpStatusCode.NotFound)]
public class UserNotFoundException : Exception
{
    [ResponseErrorProperty("userId")]
    public string UserId { get; }

    public UserNotFoundException(string userId)
        : base($"User {userId} not found") => UserId = userId;
}

Response:

{
  "code": "USER_NOT_FOUND",
  "message": "User abc-123 not found",
  "userId": "abc-123"
}

Custom Exception Handlers

Register custom handlers for specialized exception types:

public class InfrastructureExceptionHandler : IApiExceptionHandler
{
    public int Order => 50; // Lower = higher priority (runs before built-in handlers at 100+)

    public bool CanHandle(Exception ex) => ex is DatabaseTimeoutException;

    public ApiErrorResponse Handle(Exception ex) =>
        new(HttpStatusCode.ServiceUnavailable, "DATABASE_TIMEOUT", ex.Message);
}

// Register
builder.Services.AddExceptionHandler<InfrastructureExceptionHandler>();

Response Customization

Add global properties to all error responses:

public class TraceIdCustomizer : IApiErrorResponseCustomizer
{
    public void Customize(ApiErrorResponse response)
    {
        response.AddProperty("traceId", Activity.Current?.Id);
        response.AddProperty("timestamp", DateTime.UtcNow.ToString("o"));
    }
}

// Register
builder.Services.AddErrorResponseCustomizer<TraceIdCustomizer>();

Validation Errors

Validation exceptions automatically include field-level details. Enable OverrideModelStateValidation: true to intercept [ApiController] automatic validation and use ErrorLens structured format:

{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "fieldErrors": [
    {
      "code": "REQUIRED_NOT_NULL",
      "property": "email",
      "message": "Email is required",
      "rejectedValue": null,
      "path": "email"
    }
  ]
}

RFC 9457 Problem Details

Enable RFC 9457 compliant application/problem+json responses:

{
  "ErrorHandling": {
    "UseProblemDetailFormat": true,
    "ProblemDetailTypePrefix": "https://api.example.com/errors/",
    "ProblemDetailConvertToKebabCase": true
  }
}

Response:

{
  "type": "https://api.example.com/errors/user-not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "User abc-123 not found",
  "code": "USER_NOT_FOUND"
}

Logging

Control logging verbosity per HTTP status code or exception type:

ErrorHandling:
  ExceptionLogging: WithStacktrace   # None | MessageOnly | WithStacktrace
  LogLevels:
    4xx: Warning
    5xx: Error
    404: Debug
  FullStacktraceHttpStatuses:
    - 5xx
  FullStacktraceClasses:
    - MyApp.CriticalException

Error Code Strategies

Default HTTP Status Mappings

Samples

Documentation

• Getting Started
• Configuration
• Validation Errors
• Custom Handlers
• Attributes
• Response Customization
• Problem Details (RFC 9457)
• JSON Field Names
• Logging
• API Reference
• YAML Template
• Changelog

🤝 Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.