Table of Contents

Class ForbiddenException

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

Exception thrown when access to a resource is forbidden.

public sealed class ForbiddenException : DispatchException, ISerializable
Inheritance
ForbiddenException
Implements
Inherited Members
Extension Methods

Examples

if (!user.HasPermission(Permission.DeleteOrders))
{
    throw new ForbiddenException("Order", "Delete");
}

Remarks

This exception indicates that the authenticated user does not have permission to perform the requested operation. It maps to HTTP status code 403 (Forbidden).

This differs from authentication failures (401 Unauthorized):

  • 401 Unauthorized: The user is not authenticated (no identity)
  • 403 Forbidden: The user IS authenticated but lacks permission

Use this exception when:

  • A user lacks the required role or permission
  • The resource is private and the user is not the owner
  • A feature is disabled for the user's subscription tier

Constructors

ForbiddenException()

Initializes a new instance of the ForbiddenException class.

public ForbiddenException()

ForbiddenException(string)

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

public ForbiddenException(string message)

Parameters

message string

The error message that explains the reason for the exception.

ForbiddenException(string, Exception?)

Initializes a new instance of the ForbiddenException class with a message and inner exception.

public ForbiddenException(string message, Exception? innerException)

Parameters

message string

The error message that explains the reason for the exception.

innerException Exception

The exception that is the cause of the current exception.

ForbiddenException(string, string)

Initializes a new instance of the ForbiddenException class with resource and operation information.

public ForbiddenException(string resource, string operation)

Parameters

resource string

The type or name of the resource.

operation string

The operation that was denied.

ForbiddenException(string, string, string)

Initializes a new instance of the ForbiddenException class with detailed permission information.

public ForbiddenException(string resource, string operation, string requiredPermission)

Parameters

resource string

The type or name of the resource.

operation string

The operation that was denied.

requiredPermission string

The permission that is required.

Properties

Operation

Gets the operation that was denied.

public string? Operation { get; }

Property Value

string

The operation name, or null if not specified.

RequiredPermission

Gets the permission that is required to perform the operation.

public string? RequiredPermission { get; }

Property Value

string

The required permission, or null if not specified.

Resource

Gets the type or name of the resource associated with this exception.

public string? Resource { get; }

Property Value

string

The resource type or name, or null if not specified.

Methods

GetProblemDetailsExtensions()

Gets additional extension data to include in problem details.

protected override 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.

MissingRole(string, string, string)

Creates a ForbiddenException for a missing role.

public static ForbiddenException MissingRole(string resource, string operation, string requiredRole)

Parameters

resource string

The type or name of the resource.

operation string

The operation that was denied.

requiredRole string

The role that is required.

Returns

ForbiddenException

A new ForbiddenException instance.

SubscriptionRequired(string, string)

Creates a ForbiddenException for a feature that requires a higher subscription tier.

public static ForbiddenException SubscriptionRequired(string feature, string requiredTier)

Parameters

feature string

The feature that is restricted.

requiredTier string

The required subscription tier.

Returns

ForbiddenException

A new ForbiddenException instance.