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

Represents a structured, machine-readable, and human-friendly error object, used to describe failures in the Zentient.Results framework.

ErrorInfo enables consistent, composable error propagation across APIs, services, and transports. It is the core error contract across the Zentient ecosystem.

ErrorInfo was created to standardize how errors are described, serialized, and propagated throughout distributed systems. It offers a flexible, extensible model for describing errors in a way that’s compatible with both machine processing and developer/operator readability.

• 📦 Structured Semantics: Encodes category, code, message, detail, and optional metadata.
• 🧱 Extensibility: Supports custom metadata and recursive inner errors (InnerErrors).
• 📡 Transport-Friendly: Maps cleanly to HTTP ProblemDetails, gRPC Status, and more.
• 💡 Traceable: Includes contextual hints for debugging, including exception-derived metadata.
• 🔁 Composability: Designed to aggregate, flatten, and nest errors for richer context.

[DataContract]
public sealed class ErrorInfo : IEquatable<ErrorInfo>

• Signature: public ErrorInfo(string category, string code, string message, string? detail = null, IDictionary<string, object?>? metadata = null, IEnumerable<ErrorInfo>? innerErrors = null)

• Summary: Initializes a new instance of ErrorInfo with full custom content.

• Parameters:

  • category (string): A high-level grouping for the error (e.g., Validation, BusinessLogic).
  • code (string): Unique machine-readable error identifier.
  • message (string): A human-readable explanation of the error.
  • detail (string?): Optional technical detail or context.
  • metadata (IDictionary<string, object?>?): Optional metadata for debugging, correlation, etc.
  • innerErrors (IEnumerable<ErrorInfo>?): Optional child errors for hierarchical nesting.

• Remarks: For simple cases, prefer static creation methods like Create() or FromException().

• Signature: public static ErrorInfo Create(string code, string message, string? category = null)

• Summary: Creates a simple error with optional category.

• Parameters:

  • code (string): Unique identifier.
  • message (string): Human-readable error description.
  • category (string?): Optional category (defaults to General).

• Return Value: ErrorInfo

• Signature: public static ErrorInfo FromException(Exception exception, string? code = null, string? category = null)

• Summary: Transforms an Exception into a structured ErrorInfo with metadata.

• Parameters:

  • exception (Exception): The caught exception.
  • code (string?): Optional override for the error code (defaults to UNHANDLED_EXCEPTION).
  • category (string?): Optional override for the category (defaults to Exception).

• Behavior: Captures type, message, stack trace, and source into metadata.

• Type: string
• Summary: The domain or grouping for the error (e.g., Validation, Timeout).
• Behavior: Used to organize and route errors logically.

• Type: string
• Summary: A unique, machine-readable identifier for the error (e.g., FIELD_REQUIRED).

• Type: string
• Summary: A localized or human-readable explanation of the error.

• Type: string?
• Summary: Optional technical or contextual details not suitable for end users.

• Type: IReadOnlyDictionary<string, object?>
• Summary: Key-value store for additional information (e.g., request ID, field name, stack trace).
• Behavior: Flattened in diagnostics and transport logs. Reserved keys: see MetadataKeys.

• Type: IReadOnlyList<ErrorInfo>
• Summary: Nested child errors, used for aggregation or drill-down insights.

• Signature: public override string ToString()
• Summary: Returns a compact, human-readable representation of the error.
• Behavior: Combines Category, Code, and Message.

var error = ErrorInfo.Create("VALIDATION_FAILED", "The name field is required.", category: "Validation");

try
{
    DoDangerousThing();
}
catch (Exception ex)
{
    return Result.Failure(ErrorInfo.FromException(ex), ResultStatus.UnhandledException);
}

var compound = new ErrorInfo(
    category: "Validation",
    code: "MULTIPLE_ERRORS",
    message: "Several issues occurred.",
    innerErrors: new[]
    {
        ErrorInfo.Create("FIELD_REQUIRED", "Name is missing."),
        ErrorInfo.Create("TOO_SHORT", "Password is too short.")
    }
);

• Keys in Metadata should be predictable. Reserved keys include:

  • exceptionMessage, exceptionType, exceptionStackTrace, validationErrors, etc.

• The InnerErrors list enables hierarchies for field-level or multi-domain validations.

• The Code field is used for programmatic handling—avoid using message strings in switch logic.

• IResult
• MetadataKeys
• ErrorCodes
• Error Serialization Format

#ErrorModel #StructuredError #ExceptionHandling #Telemetry #DiagnosticModel #ZentientCore

Last Updated: 2025-06-21 Version: 0.4.0