Franz.Common.Errors 3.0.0

dotnet add package Franz.Common.Errors --version 3.0.0
                    
NuGet\Install-Package Franz.Common.Errors -Version 3.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Franz.Common.Errors" Version="3.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Franz.Common.Errors" Version="3.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Franz.Common.Errors" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Franz.Common.Errors --version 3.0.0
                    
#r "nuget: Franz.Common.Errors, 3.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Franz.Common.Errors@3.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Franz.Common.Errors&version=3.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Franz.Common.Errors&version=3.0.0
                    
Install as a Cake Tool

Franz.Common.Errors

Exception types and a small error payload contract for expressing application failures.

Overview

Exception types and a small error payload contract for expressing application failures.

Installation

dotnet add package Franz.Common.Errors

Exception hierarchy

The package contains two related groups:

  • ExceptionBase is an abstract serializable base class with parameterless, message, and message-plus-inner-exception constructors.
  • NotFoundException, PreconditionFailedException, TechnicalException, UnauthorizedException, and FunctionalException derive from ExceptionBase.
  • ForbiddenException derives directly from Exception.
  • BusinessException also derives directly from Exception and carries a stable Code plus read-only Metadata.

The exception types provide semantic classification. They do not themselves map to HTTP status codes, write logs, or serialize an API response. The application boundary must define that mapping.

Usage

using Franz.Common.Errors;

public Order GetOrder(Guid id)
{
    var order = repository.Find(id);

    if (order is null)
        throw new NotFoundException($"Order '{id}' was not found.");

    return order;
}

For machine-readable business failures, use BusinessException and stable codes that clients can depend on:

throw new BusinessException(
    "order.state.invalid",
    "The order cannot be confirmed in its current state.",
    new Dictionary<string, object?>
    {
        ["orderId"] = orderId,
        ["state"] = currentState
    });

Metadata is copied into an internal dictionary at construction. Treat it as diagnostic data: do not include credentials, tokens, personal secrets, or other sensitive values.

ErrorResponse

ErrorResponse is a minimal mutable payload with a required-by-convention Message string and optional StackTrace. It does not contain a status code, error code, details collection, or automatic exception conversion.

var response = new ErrorResponse
{
    Message = "The requested resource was not found."
};

Do not expose stack traces to untrusted clients in production. Prefer a centrally defined exception-to-response policy at the API boundary.

Test failure helpers

TestExceptions provides named factories for intentionally throwing ordinary Exception instances in demonstrations and tests: BananaRepublic(), Monster(), VodkaCoffeePot(), and FriendlyReminder(), each with a French variant. These are not production exception types and carry no structured error contract.

Design guidance

Use exceptions for exceptional control flow and boundary translation, not as a replacement for expected validation results. Keep business error codes stable, separate from transport-specific HTTP semantics.

License

MIT. See LICENSE.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages (16)

Showing the top 5 NuGet packages that depend on Franz.Common.Errors:

Package Downloads
Franz.Common.Reflection

Shared utility library for the Franz Framework.

Franz.Common.Business

Shared utility library for the Franz Framework.

Franz.Common.Messaging

Shared utility library for the Franz Framework.

Franz.Common.EntityFramework

Shared utility library for the Franz Framework.

Franz.Common.Http

Shared utility library for the Franz Framework.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0 449 11/10/2026
2.3.4 836 11/1/2026
2.3.3 714 10/28/2026
2.3.2 524 10/27/2026
2.3.1 587 10/26/2026
2.3.0 758 7/21/2026
2.2.19 598 7/19/2026
2.2.18 595 7/19/2026
2.2.17 2,016 7/12/2026
2.2.16 600 7/2/2026
2.2.15 592 6/29/2026
2.2.14 592 6/29/2026
2.2.13 591 6/29/2026
2.2.12 588 6/28/2026
2.2.11 593 6/28/2026
2.2.10 605 6/28/2026
2.2.9 589 6/28/2026
2.2.8 582 6/28/2026
2.2.7 605 6/7/2026
2.2.6 599 6/6/2026
Loading failed