ExceptionsAPI 1.0.0

.NET 6.0
dotnet add package ExceptionsAPI --version 1.0.0
NuGet\Install-Package ExceptionsAPI -Version 1.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="ExceptionsAPI" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ExceptionsAPI --version 1.0.0
#r "nuget: ExceptionsAPI, 1.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.
// Install ExceptionsAPI as a Cake Addin
#addin nuget:?package=ExceptionsAPI&version=1.0.0

// Install ExceptionsAPI as a Cake Tool
#tool nuget:?package=ExceptionsAPI&version=1.0.0

Nuget Version Nuget Downloads Continuous Integration


Standardizing Exception Handling Middleware to enhance API Developer experience.

ExceptionsAPI allows applications to determine status codes and error messages for exceptions thrown in the application. This allows the application to be more flexible in how it handles exceptions and allows the application to be more consistent in how it handles exceptions.

Quick Start


Register Exception Status Codes (Program.cs or Startup.cs)


Activate Exception Handling Middleware (Program.cs or Startup.cs)



With the setup in the previous section, now throwing your YourCustomOrBuiltInException exception type will generate the following output in the response body:

Exception Code:

throw new YourCustomOrBuiltInException("This Message Will Get Logged And Returned");

Http Response Body (ProblemDetails):

  "type": "YourCustomOrBuiltInException",
  "title": "GatewayTimeout",
  "status": 504,
  "detail": "This Message Will Get Logged And Returned",
  "instance": "/api/YourEndpoint/PathAndQueryRequest?IncludingParams=true",
  "correlationId": "782e230a-7fb7-43aa-8d64-56d27c9f0e27"

ADDITIONALLY, adding Exception.Data to show multiple errors will be returned as below:

Exception Code:

var exceptionToBeThrown = new YourCustomOrBuiltInException("This Message Will Get Logged And Returned");

exceptionToBeThrown.Data.Add("TestField1", "This Failed for some reason");
exceptionToBeThrown.Data.Add("TestField2", "This Failed for some other reason");
exceptionToBeThrown.Data.Add("TestField3", "This Failed for another reason");

throw exceptionToBeThrown;

Http Response Body (ValidationProblemDetails):

  "type": "YourCustomOrBuiltInException",
  "title": "GatewayTimeout",
  "status": 504,
  "detail": "This Message Will Get Logged And Returned",
  "instance": "/api/YourEndpoint/PathAndQueryRequest?IncludingParams=true",
  "correlationId": "da3f8dde-e4a0-4932-9508-36e52cbad480",
  "errors": {
    "TestField1": ["This Failed for some reason"],
    "TestField2": ["This Failed for some other reason"],
    "TestField3": ["This Failed for another reason"]

Full Setup Sample (Program.cs)

using ExceptionsAPI;
using System.Net;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);


// Register custom exceptions and status codes
        // Chain multiple exceptions to the same status code to various status codes

WebApplication app = builder.Build();


// Register Exceptions API Middleware

Status Code & Error Message Runtime Determination

You can establish specific status codes and error messages for specific exceptions at runtime. This allows you to have a single exception type that can be thrown in multiple places and have different status codes and error messages depending on the context.

  1. Create a class that inherits from the abstract class ExceptionsAPIException. This class will allow an input of a status code as well as an optional client error message (initialized during exception creation).

    public class CustomClientException : ExceptionsAPIException
        private const HttpStatusCode defaultStatusCode = HttpStatusCode.Conflict;
        // You can set a constructor to pass a default status code
        public CustomClientException(string message) :
            base(defaultStatusCode, message)
        { }
        // You can create a constructor to receive a status code dynamically
        public CustomClientException(HttpStatusCode httpStatusCode, string message) :
            base(httpStatusCode, message)
        { }
        public CustomClientException(string message, Exception innerException) :
            base(defaultStatusCode, message, innerException)
        { }
        public CustomClientException(HttpStatusCode httpStatusCode, string message, Exception innerException) :
            base(httpStatusCode, message, innerException)
        { }
  2. Throwing the below exception will result in the following response body:

    throw new CustomClientException(HttpStatusCode.BadRequest, "Internal Message")
        // "Internal Message" will be logged
        // "External Message" will be returned
        // "Internal Message" will be returned if ClientErrorMessage is not set
        ClientErrorMessage = "External Message"


      "type": "CustomClientException",
      "title": "BadRequest",
      "status": 400,
      "detail": "External Message",
      "instance": "/api/YourEndpoint/PathAndQueryRequest?IncludingParams=true"
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0 88 5/26/2023
1.0.0-beta1 71 4/25/2023
1.0.0-alpha1 81 4/13/2023