API Reference ErrorCodes - ulfbou/Zentient.Results GitHub Wiki

📘 API Reference: `static class` – `ErrorCodes`

Namespace: Zentient.Results.Constants Assembly: Zentient.Results.dll Available since: v0.1.0

📖 Summary

Defines standardized constant error codes used throughout the Zentient framework for common categories of operational failures.

ErrorCodes enables uniform, machine-readable identifiers for classifying errors, ensuring consistent handling across services, protocols, and diagnostics.

💡 Design Philosophy / Rationale

The ErrorCodes static class provides a centralized, shared vocabulary for identifying error types across all layers of a system. By standardizing error code values:

🔄 Interoperability is improved between microservices, protocols, telemetry, and client applications.
📡 Telemetry, logging, and monitoring tools can classify errors without relying on brittle message parsing.
🎯 Intentional classification ensures errors are actionable and semantically accurate.
🧩 Adapters and converters (e.g., ProblemDetails, gRPC metadata) use these constants to generate appropriate status codes and response formats.

Each code is intentionally short, clear, and unambiguous for both machine processing and developer familiarity.

🔖 Type Signature

public static class ErrorCodes

📂 Members

Constant Name	Value	Description
`General`	`"GENERAL_ERROR"`	A generic fallback for unknown or uncategorized failures.
`Validation`	`"VALIDATION_ERROR"`	Input validation failed (e.g., format, range, missing fields).
`NotFound`	`"RESOURCE_NOT_FOUND"`	Requested entity was not found.
`Unauthorized`	`"UNAUTHORIZED_ACCESS"`	Authentication failed or was missing.
`Forbidden`	`"FORBIDDEN_ACCESS"`	Access was denied due to lack of permission.
`Conflict`	`"RESOURCE_CONFLICT"`	A uniqueness or state conflict was detected.
`Exception`	`"UNHANDLED_EXCEPTION"`	Uncaught exception occurred.
`Timeout`	`"OPERATION_TIMEOUT"`	The operation exceeded allowed time.
`BadGateway`	`"BAD_GATEWAY"`	An upstream service returned a failure.
`ServiceUnavailable`	`"SERVICE_UNAVAILABLE"`	A required service is temporarily unavailable.
`NotImplemented`	`"NOT_IMPLEMENTED"`	The feature or method is not implemented.
`Concurrency`	`"CONCURRENCY_VIOLATION"`	An optimistic concurrency control error occurred.
`TooManyRequests`	`"TOO_MANY_REQUESTS"`	Client has exceeded rate limits.
`ExternalService`	`"EXTERNAL_SERVICE_ERROR"`	Dependency failed or returned unexpected result.
`BusinessLogic`	`"BUSINESS_LOGIC_ERROR"`	Domain rule enforcement failed.
`Request`	`"BAD_REQUEST_FORMAT"`	Malformed input data or request structure.
`InternalServerError`	`"INTERNAL_SERVER_ERROR"`	An unexpected server-side failure occurred.
`ResourceGone`	`"RESOURCE_GONE"`	The requested resource has been permanently removed.

🧪 Usage Examples

var error = new ErrorInfo(
    category: "Validation",
    code: ErrorCodes.Validation,
    message: "Email address must be a valid format."
);

if (result.IsFailure && result.Errors.Any(e => e.Code == ErrorCodes.Unauthorized))
{
    return Unauthorized();
}

⚠️ Remarks

These codes are machine-readable, predictable, and reusable. Do not localize or translate them.
Codes should remain stable to ensure telemetry, clients, and automated tools function predictably.
ErrorCodes is used in conjunction with ErrorInfo and IResult to structure consistent failure responses.
These codes often correlate to specific ResultStatus values and HTTP status codes via endpoint adapters.

🧩 Integration and Interoperability

Consumer Layer	Usage Example
`ErrorInfo`	Populates `code` field for structured errors.
HTTP	Mapped to RFC 7807 ProblemDetails `type` or `title`.
gRPC	Used in gRPC `Metadata` headers for error classification.
Telemetry/Tracing	Emitted as `error.code` tag in OpenTelemetry spans.
Messaging Systems	Encoded into headers or payloads for fault routing.

📚 See Also

🏷️ Tags

#API #ErrorCodes #ErrorClassification #StableContract #Interop #ZentientCore #DiagnosticModel

Last Updated: 2025-06-21 Version: 0.4.0