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
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
reasonstringThe 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
resourceTypestringThe type of resource that was not found.
resourceIdstringThe 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
reasonstringThe 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
errorsIDictionary<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
exceptionExceptionThe exception to convert.
includeDetailsboolWhether to include detailed error information.
Returns
- DispatchProblemDetails
A problem details instance.