Class Error

Namespace

FunctionalDdd

Assembly

FunctionalDdd.RailwayOrientedProgramming.dll

Base class for all error types in the functional DDD library. Errors represent failure states and contain structured information about what went wrong.

public class Error : IEquatable<Error>

Inheritance

object

Error

Implements

IEquatable<Error>

Derived

AggregateError

BadRequestError

ConflictError

DomainError

ForbiddenError

NotFoundError

RateLimitError

ServiceUnavailableError

UnauthorizedError

UnexpectedError

ValidationError

Inherited Members

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Extension Methods

CombineErrorExtensions.Combine(Error?, Error)

MaybeExtensions.AsMaybe<T>(T)

MaybeExtensions.ToResult<TValue>(TValue)

NullableExtensions.ToResult<T>(T?, Error)

Remarks

Use the static factory methods (Validation, NotFound, etc.) to create specific error types. All errors have a Code for programmatic handling and a Detail for human-readable messages.

Constructors

Error(string, string)

Initializes a new instance of the Error class with the specified detail and code.

public Error(string detail, string code)

Parameters

detail string

The human-readable error description.

code string

The machine-readable error code.

Error(string, string, string?)

Initializes a new instance of the Error class with the specified detail, code, and instance identifier.

public Error(string detail, string code, string? instance)

Parameters

detail string

The human-readable error description.

code string

The machine-readable error code.

instance string

An optional identifier for the specific instance that caused the error.

Properties

Code

Gets the machine-readable error code. Use this for programmatic error handling.

public string Code { get; }

Property Value

string

A string code like "validation.error" or "not.found.error".

Detail

Gets the human-readable error description. Use this for displaying error messages to users or in logs.

public string Detail { get; }

Property Value

string

A descriptive message explaining what went wrong.

Instance

Gets an optional identifier for the specific instance that caused the error (e.g., a resource ID).

public string? Instance { get; }

Property Value

string

An instance identifier, or null if not applicable.

Methods

BadRequest(string, string?)

Creates a BadRequestError indicating the request was malformed or invalid.

public static BadRequestError BadRequest(string detail, string? instance = null)

Parameters

detail string

Description of why the request is bad.

instance string

Optional identifier for the bad request.

Returns

BadRequestError

A BadRequestError.

Remarks

Use this for syntactic errors or malformed requests, not for business rule violations (use Validation instead).

BadRequest(string, string, string?)

Creates a BadRequestError with a custom error code.

public static BadRequestError BadRequest(string detail, string code, string? instance)

Parameters

detail string

Description of why the request is bad.

code string

Custom error code to use instead of the default "bad.request.error".

instance string

Optional identifier for the bad request.

Returns

BadRequestError

A BadRequestError with the specified code.

Conflict(string, string?)

Creates a ConflictError indicating a conflict with the current state.

public static ConflictError Conflict(string detail, string? instance = null)

Parameters

detail string

Description of the conflict.

instance string

Optional identifier for the conflicting resource.

Returns

ConflictError

A ConflictError.

Examples

Error.Conflict("Email address already in use")
Error.Conflict("Cannot delete user with active subscriptions")

Conflict(string, string, string?)

Creates a ConflictError with a custom error code.

public static ConflictError Conflict(string detail, string code, string? instance)

Parameters

detail string

Description of the conflict.

code string

Custom error code to use instead of the default "conflict.error".

instance string

Optional identifier for the conflicting resource.

Returns

ConflictError

A ConflictError with the specified code.

Domain(string, string?)

Creates a DomainError indicating a business rule violation.

public static DomainError Domain(string detail, string? instance = null)

Parameters

detail string

Description of the business rule that was violated.

instance string

Optional identifier for the entity or operation.

Returns

DomainError

A DomainError.

Examples

Error.Domain("Cannot withdraw more than account balance")
Error.Domain("Minimum order quantity is 10 units")
Error.Domain("Cannot cancel order after shipment")

Remarks

Use this for domain logic violations that prevent the operation from completing. This is distinct from validation errors (field-level) and conflicts (state-based). Maps to HTTP 422 Unprocessable Entity.

Domain(string, string, string?)

Creates a DomainError with a custom error code.

public static DomainError Domain(string detail, string code, string? instance)

Parameters

detail string

Description of the business rule that was violated.

code string

Custom error code to use instead of the default "domain.error".

instance string

Optional identifier for the entity or operation.

Returns

DomainError

A DomainError with the specified code.

Equals(Error?)

Determines equality based solely on the error Code.

public bool Equals(Error? other)

Parameters

other Error

The error to compare with.

Returns

bool

True if the error codes match; false otherwise.

Remarks

IMPORTANT: Two errors are considered equal if they have the same Code, regardless of their Detail, Instance, or concrete type. This design allows treating errors with the same code as equivalent for programmatic handling. Example: Error.NotFound("User not found", "user-1") == Error.NotFound("Product not found", "user-1") returns true because both have the code "not.found.error".

Equals(object?)

Determines whether the specified object is equal to the current Error instance.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current Error instance.

Returns

bool

true if the specified object is an Error and is equal to the current instance; otherwise, false.

Remarks

This method supports object-based equality comparison. Use this method when the type of the object to compare is not known at compile time.

Forbidden(string, string?)

Creates a ForbiddenError indicating the user lacks permission.

public static ForbiddenError Forbidden(string detail, string? instance = null)

Parameters

detail string

Description of why access is forbidden.

instance string

Optional identifier for the forbidden resource.

Returns

ForbiddenError

A ForbiddenError.

Remarks

Use this when the user is authenticated but doesn't have permission to access the resource.

Forbidden(string, string, string?)

Creates a ForbiddenError with a custom error code.

public static ForbiddenError Forbidden(string detail, string code, string? instance)

Parameters

detail string

Description of why access is forbidden.

code string

Custom error code to use instead of the default "forbidden.error".

instance string

Optional identifier for the forbidden resource.

Returns

ForbiddenError

A ForbiddenError with the specified code.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

NotFound(string, string?)

Creates a NotFoundError indicating a requested resource was not found.

public static NotFoundError NotFound(string detail, string? instance = null)

Parameters

detail string

Description of what was not found.

instance string

Optional identifier for the missing resource.

Returns

NotFoundError

A NotFoundError.

Examples

Error.NotFound($"User with ID {userId} not found", userId)
Error.NotFound("Product not found in catalog")

NotFound(string, string, string?)

Creates a NotFoundError with a custom error code.

public static NotFoundError NotFound(string detail, string code, string? instance)

Parameters

detail string

Description of what was not found.

code string

Custom error code to use instead of the default "not.found.error".

instance string

Optional identifier for the missing resource.

Returns

NotFoundError

A NotFoundError with the specified code.

RateLimit(string, string?)

Creates a RateLimitError indicating too many requests have been made.

public static RateLimitError RateLimit(string detail, string? instance = null)

Parameters

detail string

Description of the rate limit violation.

instance string

Optional identifier for the client or resource being rate limited.

Returns

RateLimitError

A RateLimitError.

Examples

Error.RateLimit("API rate limit exceeded. Please try again in 60 seconds")
Error.RateLimit("Too many login attempts. Account temporarily locked")

Remarks

Use this when a client has exceeded their request quota or rate limit. Maps to HTTP 429 Too Many Requests.

RateLimit(string, string, string?)

Creates a RateLimitError with a custom error code.

public static RateLimitError RateLimit(string detail, string code, string? instance)

Parameters

detail string

Description of the rate limit violation.

code string

Custom error code to use instead of the default "rate.limit.error".

instance string

Optional identifier for the client or resource being rate limited.

Returns

RateLimitError

A RateLimitError with the specified code.

ServiceUnavailable(string, string?)

Creates a ServiceUnavailableError indicating temporary service unavailability.

public static ServiceUnavailableError ServiceUnavailable(string detail, string? instance = null)

Parameters

detail string

Description of why the service is unavailable.

instance string

Optional identifier for the unavailable service or resource.

Returns

ServiceUnavailableError

A ServiceUnavailableError.

Examples

Error.ServiceUnavailable("Service is under maintenance. Please try again later")
Error.ServiceUnavailable("External payment gateway is temporarily unavailable")

Remarks

Use this when the service is temporarily unable to handle the request. This indicates a temporary condition - the service is expected to be available again. Maps to HTTP 503 Service Unavailable.

ServiceUnavailable(string, string, string?)

Creates a ServiceUnavailableError with a custom error code.

public static ServiceUnavailableError ServiceUnavailable(string detail, string code, string? instance)

Parameters

detail string

Description of why the service is unavailable.

code string

Custom error code to use instead of the default "service.unavailable.error".

instance string

Optional identifier for the unavailable service or resource.

Returns

ServiceUnavailableError

A ServiceUnavailableError with the specified code.

ToString()

Returns a string that represents the current object, including its type, code, detail, and instance information.

public override string ToString()

Returns

string

A string containing the type name, code, detail, and instance values of the object. If the instance is null, "N/A" is used.

Unauthorized(string, string?)

Creates an UnauthorizedError indicating authentication is required.

public static UnauthorizedError Unauthorized(string detail, string? instance = null)

Parameters

detail string

Description of why authorization failed.

instance string

Optional identifier for the unauthorized request.

Returns

UnauthorizedError

An UnauthorizedError.

Remarks

Use this when the user is not authenticated (not logged in).

Unauthorized(string, string, string?)

Creates an UnauthorizedError with a custom error code.

public static UnauthorizedError Unauthorized(string detail, string code, string? instance)

Parameters

detail string

Description of why authorization failed.

code string

Custom error code to use instead of the default "unauthorized.error".

instance string

Optional identifier for the unauthorized request.

Returns

UnauthorizedError

An UnauthorizedError with the specified code.

Unexpected(string, string?)

Creates an UnexpectedError indicating an unexpected system error occurred.

public static UnexpectedError Unexpected(string detail, string? instance = null)

Parameters

detail string

Description of what went wrong.

instance string

Optional identifier for the operation that failed.

Returns

UnexpectedError

An UnexpectedError.

Remarks

Use this for system errors, infrastructure failures, or exceptions. This typically maps to HTTP 500 Internal Server Error.

Unexpected(string, string, string?)

Creates an UnexpectedError with a custom error code.

public static UnexpectedError Unexpected(string detail, string code, string? instance)

Parameters

detail string

Description of what went wrong.

code string

Custom error code to use instead of the default "unexpected.error".

instance string

Optional identifier for the operation that failed.

Returns

UnexpectedError

An UnexpectedError with the specified code.

Validation(ImmutableArray<FieldError>, string, string?)

Creates a ValidationError for multiple field validation failures.

public static ValidationError Validation(ImmutableArray<ValidationError.FieldError> fieldDetails, string detail = "", string? instance = null)

Parameters

fieldDetails ImmutableArray<ValidationError.FieldError>

Collection of field-specific validation errors.

detail string

Overall error description.

instance string

Optional identifier for the instance being validated.

Returns

ValidationError

A ValidationError containing all field errors.

Examples

var errors = ImmutableArray.Create(
    new FieldError("email", "Invalid format"),
    new FieldError("age", "Must be 18 or older")
);
Error.Validation(errors, "User validation failed")

Validation(ImmutableArray<FieldError>, string, string?, string)

Creates a ValidationError for multiple field validation failures with a custom error code.

public static ValidationError Validation(ImmutableArray<ValidationError.FieldError> fieldDetails, string detail, string? instance, string code)

Parameters

fieldDetails ImmutableArray<ValidationError.FieldError>

Collection of field-specific validation errors.

detail string

Overall error description.

instance string

Optional identifier for the instance being validated.

code string

Custom error code to use instead of the default "validation.error".

Returns

ValidationError

A ValidationError containing all field errors with the specified code.

Validation(string, string, string?, string?)

Creates a ValidationError for a single field validation failure.

public static ValidationError Validation(string fieldDetail, string fieldName = "", string? detail = null, string? instance = null)

Parameters

fieldDetail string

Description of what's wrong with the field value.

fieldName string

Name of the field that failed validation. Empty string if not field-specific.

detail string

Optional overall error detail. If null, uses fieldDetail.

instance string

Optional identifier for the instance being validated.

Returns

ValidationError

A ValidationError representing the validation failure.

Examples

Error.Validation("Email address is not valid", "email")
Error.Validation("Age must be 18 or older", "age")