Table of Contents

Class DispatchProblemDetails

Namespace
Excalibur.Dispatch.Exceptions
Assembly
Excalibur.Dispatch.dll

Implements RFC 7807 Problem Details for HTTP APIs with additional fields for distributed tracing. Provides a standardized format for error responses across the Excalibur framework.

public sealed class DispatchProblemDetails
Inheritance
DispatchProblemDetails
Inherited Members
Extension Methods

Properties

Category

Gets or sets the error category for classification.

[JsonPropertyName("category")]
public string? Category { get; set; }

Property Value

string

The error category for classification.

CorrelationId

Gets or sets the correlation ID for tracing the error across services.

[JsonPropertyName("correlationId")]
public string? CorrelationId { get; set; }

Property Value

string

The correlation ID for tracing the error across services.

Detail

Gets or sets a human-readable explanation specific to this occurrence of the problem.

[JsonPropertyName("detail")]
public string? Detail { get; set; }

Property Value

string

A human-readable explanation specific to this occurrence of the problem.

DiagnosticReason

Gets or sets the server-side diagnostic reason for a denial. This value is deliberately NOT serialized: it exists so a caller of ForUnauthorized(string?) or ForForbidden(string?) can log the specific reason alongside CorrelationId without disclosing it across the trust boundary.

[JsonIgnore]
public string? DiagnosticReason { get; set; }

Property Value

string

The server-side diagnostic reason for a denial, or null when none was supplied.

Remarks

Authorization vocabulary — policy names, role names, permission identifiers and evaluation failure messages — must never reach a 401 or 403 response body. A legitimate caller cannot act on such a name; only an attacker enumerating endpoints benefits from it. ASP.NET Core's own 403 carries no reason for the same reason.

ErrorCode

Gets or sets the error code for programmatic error handling.

[JsonPropertyName("errorCode")]
public string? ErrorCode { get; set; }

Property Value

string

The error code for programmatic error handling.

Extensions

Gets additional extension data for the problem details.

[JsonExtensionData]
public Dictionary<string, object?>? Extensions { get; init; }

Property Value

Dictionary<string, object>

Additional extension data for the problem details.

Instance

Gets or sets a URI reference that identifies the specific occurrence of the problem.

[JsonPropertyName("instance")]
public string? Instance { get; set; }

Property Value

string

A URI reference that identifies the specific occurrence of the problem.

Severity

Gets or sets the error severity level.

[JsonPropertyName("severity")]
public string? Severity { get; set; }

Property Value

string

The error severity level.

SpanId

Gets or sets the span ID from distributed tracing.

[JsonPropertyName("spanId")]
public string? SpanId { get; set; }

Property Value

string

The span ID from distributed tracing.

Status

Gets or sets the HTTP status code generated by the origin server for this occurrence of the problem.

[JsonPropertyName("status")]
public int? Status { get; set; }

Property Value

int?

The HTTP status code generated by the origin server for this occurrence of the problem.

SuggestedAction

Gets or sets suggested actions to resolve the error.

[JsonPropertyName("suggestedAction")]
public string? SuggestedAction { get; set; }

Property Value

string

Suggested actions to resolve the error.

Timestamp

Gets or sets the timestamp when the error occurred.

[JsonPropertyName("timestamp")]
public DateTimeOffset? Timestamp { get; set; }

Property Value

DateTimeOffset?

The timestamp when the error occurred.

Title

Gets or sets a short, human-readable summary of the problem type. Should not change from occurrence to occurrence of the problem.

[JsonPropertyName("title")]
public string? Title { get; set; }

Property Value

string

A short, human-readable summary of the problem type. Should not change from occurrence to occurrence of the problem.

TraceId

Gets or sets the trace ID from distributed tracing.

[JsonPropertyName("traceId")]
public string? TraceId { get; set; }

Property Value

string

The trace ID from distributed tracing.

Type

Gets or sets a URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.

[JsonPropertyName("type")]
public string Type { get; set; }

Property Value

string

A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type.

Methods

ForForbidden(string?)

Creates a forbidden problem details instance.

public static DispatchProblemDetails ForForbidden(string? reason = null)

Parameters

reason string

The reason for the forbidden access. Recorded on DiagnosticReason for server-side logging ONLY — it is never serialized into the response body.

Returns

DispatchProblemDetails

A problem details instance for forbidden errors.

ForNotFound(string, string?)

Creates a not found problem details instance.

public static DispatchProblemDetails ForNotFound(string resourceType, string? resourceId = null)

Parameters

resourceType string

The type of resource that was not found.

resourceId string

The ID of the resource that was not found.

Returns

DispatchProblemDetails

A problem details instance for not found errors.

ForUnauthorized(string?)

Creates an unauthorized problem details instance.

public static DispatchProblemDetails ForUnauthorized(string? reason = null)

Parameters

reason string

The reason for the unauthorized access. Recorded on DiagnosticReason for server-side logging ONLY — it is never serialized into the response body.

Returns

DispatchProblemDetails

A problem details instance for unauthorized errors.

ForValidation(IDictionary<string, string[]>)

Creates a validation problem details instance.

public static DispatchProblemDetails ForValidation(IDictionary<string, string[]> errors)

Parameters

errors IDictionary<string, string[]>

The validation errors.

Returns

DispatchProblemDetails

A problem details instance for validation errors.

FromException(Exception, bool)

Creates a problem details instance from an exception.

public static DispatchProblemDetails FromException(Exception exception, bool includeDetails = false)

Parameters

exception Exception

The exception to convert.

includeDetails bool

Whether to include detailed error information.

Returns

DispatchProblemDetails

A problem details instance.