Table of Contents

Class ApiException

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Represents an exception specifically designed for API-related errors.

public class ApiException : Exception, ISerializable
Inheritance
ApiException
Implements
Derived
Inherited Members
Extension Methods

Constructors

ApiException()

Initializes a new instance of the ApiException class with a default error message.

public ApiException()

ApiException(int, string?, Exception?)

Initializes a new instance of the ApiException class with a specified status code, error message, and inner exception.

public ApiException(int statusCode, string? message, Exception? innerException)

Parameters

statusCode int

The HTTP status code associated with the exception.

message string

The error message describing the exception. If null, a default message is used.

innerException Exception

The exception that caused the current exception.

Exceptions

ArgumentOutOfRangeException

Thrown if the statusCode is outside the valid range (100-599).

ApiException(string)

Initializes a new instance of the ApiException class with a specified error message.

public ApiException(string message)

Parameters

message string

The error message describing the exception.

ApiException(string, Exception?)

Initializes a new instance of the ApiException class with a specified error message and an inner exception that caused this exception.

public ApiException(string message, Exception? innerException)

Parameters

message string

The error message describing the exception.

innerException Exception

The exception that caused the current exception.

Properties

Id

Gets a unique identifier for the error instance.

public Guid Id { get; }

Property Value

Guid

A unique identifier for the error instance, lazily generated on first access.

StatusCode

Gets the HTTP status code associated with this exception.

public int StatusCode { get; init; }

Property Value

int

The HTTP status code associated with this exception.

Methods

GetProblemDetailsErrorCode()

Gets the error code to include in problem details.

protected virtual int GetProblemDetailsErrorCode()

Returns

int

The error code. Defaults to the HTTP status code.

Remarks

Derived types can override this method to provide a more specific error code that consumers can use for programmatic error handling.

GetProblemDetailsExtensions()

Gets additional extension data to include in problem details.

protected virtual IDictionary<string, object?>? GetProblemDetailsExtensions()

Returns

IDictionary<string, object>

A dictionary of extension data to include in the problem details response, or null if no extensions should be added.

Remarks

Derived types can override this method to add type-specific data to the problem details response. For example, a ValidationException might include a dictionary of field-level validation errors.

The returned dictionary keys will be added to the problem details Extensions collection.

ToProblemDetails()

Converts this exception to RFC 7807 problem details format.

public virtual MessageProblemDetails ToProblemDetails()

Returns

MessageProblemDetails

A MessageProblemDetails instance representing this exception.

Remarks

This method creates a standardized problem details response suitable for API error responses. The generated problem details follows RFC 7807 and includes:

  • Type: A URN derived from the exception type name
  • Title: The exception type name in human-readable form
  • ErrorCode: From GetProblemDetailsErrorCode() (defaults to status code)
  • Status: The HTTP status code
  • Detail: The exception message
  • Instance: A unique URN using the exception's Id
  • Extensions: From GetProblemDetailsExtensions() (derived types can add custom data)

Derived classes can override GetProblemDetailsErrorCode() and GetProblemDetailsExtensions() to customize the problem details without overriding the entire method.