Developer Wisdom: Exception Strategy — Business vs Technical (and Why Error Codes Matter)

1. Introduction

In real-world systems, exceptions are not just “errors” — they are part of how the system communicates outcomes. The key is knowing which outcomes are expected (business rules) and which indicate unintended failure (technical faults).

This post introduces a simple, scalable strategy: Business Exception = expected based on entity values, Technical Exception = unknown/unintended, and shows how to turn business failures into predictable API responses using ProblemDetails and bounded-context error-code ranges.

2. Business vs Technical Exceptions

Business Exception (Expected)

A business exception happens when the request is valid, understood, and authenticated — but the domain rules reject it based on entity state. This is an expected outcome that client code should be prepared to handle.

• Cart expired and checkout is not allowed
• Insufficient account balance for withdrawal
• Registration blocked due to duplicate email

Technical Exception (Unintended)

A technical exception represents an unintended failure — bug, infrastructure issue, dependency outage, or contract violation. The caller cannot fix it and should not be forced to interpret it as part of the domain contract.

• Database timeout / connection failure
• Null reference due to programmer error
• External service unavailable

3. How the System Should Behave for Business Exceptions

Since business exceptions are expected outcomes, the system should treat them as client-actionable results, not “system failures”.

4. Error Code Ranges per Bounded Context

A practical pattern used in mature APIs is to allocate error code ranges per bounded context. This helps with observability, ownership, and predictable client-side handling.

Along with a numeric errorCode, keep a stable errorKey (e.g. CART_EXPIRED) for readability and future localization.

5. ProblemDetails + HTTP Status Mapping

For APIs, you want business exceptions to translate into a consistent response shape. ProblemDetails (RFC 7807) is a standard approach supported by ASP.NET Core.

Recommended mapping (simple and consistent)

• 400: request invalid (missing fields, invalid shape)
• 401 / 403: authentication / authorization outcomes
• 404: resource not found from caller’s perspective
• 409: valid request, but blocked by current domain state (very common for business rules)
• 422: domain validation failed (optional — pick one style and standardize)

Example: business exception returned as ProblemDetails

{
  "type": "https://api.techwayfit.com/problems/business-rule",
  "title": "Business rule violation",
  "status": 409,
  "detail": "Cart has expired and cannot be checked out.",
  "extensions": {
    "errorCode": 605,
    "errorKey": "CART_EXPIRED",
    "boundary": "Cart",
    "correlationId": "e3f5c7b2..."
  }
}

6. C# Exception Hierarchy Guidelines

Keep business and technical exceptions separate. This gives clarity to callers and helps your platform handle technical faults centrally.

Separate exception roots

public abstract class TechnicalException : Exception
{
    protected TechnicalException(string message, Exception? inner = null)
        : base(message, inner) { }
}

public abstract class BusinessException : Exception
{
    public int ErrorCode { get; }
    public string ErrorKey { get; }
    public string Boundary { get; }

    protected BusinessException(string boundary, int errorCode, string errorKey, string message)
        : base(message)
    {
        Boundary = boundary;
        ErrorCode = errorCode;
        ErrorKey = errorKey;
    }
}

Define bounded context code ranges

public static class ErrorCodeRanges
{
    public static readonly (int Start, int End) Login = (500, 520);
    public static readonly (int Start, int End) Registration = (520, 550);
    public static readonly (int Start, int End) Cart = (600, 630);

    public static bool InRange((int Start, int End) range, int code)
        => code >= range.Start && code <= range.End;
}

Example: Cart expired business exception

public sealed class CartExpiredException : BusinessException
{
    public CartExpiredException()
        : base(boundary: "Cart",
               errorCode: 605,
               errorKey: "CART_EXPIRED",
               message: "Cart has expired and cannot be checked out.")
    {
        // Prefer enforcing via tests or a factory; shown inline for clarity.
        if (!ErrorCodeRanges.InRange(ErrorCodeRanges.Cart, ErrorCode))
            throw new InvalidOperationException("Cart error code out of allowed range.");
    }
}

7. ASP.NET Core Middleware: Translate Exceptions Once

Middleware is a clean place to translate exceptions into HTTP responses. It avoids repeating try/catch in every controller and ensures consistent ProblemDetails output.

public sealed class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;

    public ExceptionHandlingMiddleware(RequestDelegate next, ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task Invoke(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (BusinessException ex)
        {
            await WriteBusinessProblemDetails(context, ex);
        }
        catch (TechnicalException ex)
        {
            _logger.LogError(ex, "Technical failure");
            await WriteTechnicalProblemDetails(context);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Unexpected failure");
            await WriteTechnicalProblemDetails(context);
        }
    }

    private static async Task WriteBusinessProblemDetails(HttpContext context, BusinessException ex)
    {
        var problem = new ProblemDetails
        {
            Title = "Business rule violation",
            Detail = ex.Message,
            Status = StatusCodes.Status409Conflict,
            Type = "https://api.techwayfit.com/problems/business-rule"
        };

        problem.Extensions["errorCode"] = ex.ErrorCode;
        problem.Extensions["errorKey"] = ex.ErrorKey;
        problem.Extensions["boundary"] = ex.Boundary;
        problem.Extensions["correlationId"] = context.TraceIdentifier;

        context.Response.StatusCode = problem.Status!.Value;
        context.Response.ContentType = "application/problem+json";
        await context.Response.WriteAsJsonAsync(problem);
    }

    private static async Task WriteTechnicalProblemDetails(HttpContext context)
    {
        var problem = new ProblemDetails
        {
            Title = "Technical error",
            Detail = "An internal error occurred.",
            Status = StatusCodes.Status500InternalServerError,
            Type = "https://api.techwayfit.com/problems/technical-error"
        };

        problem.Extensions["correlationId"] = context.TraceIdentifier;

        context.Response.StatusCode = problem.Status!.Value;
        context.Response.ContentType = "application/problem+json";
        await context.Response.WriteAsJsonAsync(problem);
    }
}

Register middleware early:

app.UseMiddleware<ExceptionHandlingMiddleware>();

8. Before vs After: Clear Contracts

Before (mixed meaning)

public void CheckoutCart(Guid cartId)
{
    var cart = _repo.Load(cartId) ?? throw new Exception("Cart not found");

    if (cart.IsExpired)
        throw new Exception("Cart expired");

    // ...
}

After (explicit business outcomes)

public void CheckoutCart(Guid cartId)
{
    var cart = _repo.Load(cartId) ?? throw new CartNotFoundException(cartId);

    if (cart.IsExpired)
        throw new CartExpiredException();

    // ...
}

9. Summary

Business exceptions are expected domain outcomes — treat them as part of your API contract with stable error codes, clear boundaries, and predictable ProblemDetails responses. Technical exceptions represent unintended failures — handle them centrally and keep them out of domain contracts.

🔜 Next: Result<T> vs Exceptions — when not to throw, and how to keep contracts explicit

10. Related Blogs

• Developer 101: Error Handling Best Practices
• SOLID Principles
• Dependency Injection