iError

iError is a structured error representation designed to standardize error signaling in software systems. It is described as a cross-language, framework-agnostic scheme that encapsulates the identity, context, and guidance for handling errors. The concept is not tied to a single language or platform, making it suitable for APIs, libraries, and service boundaries.

The core structure of iError includes a domain or origin, a numeric code, a human-readable message, and optional metadata. The domain indicates the subsystem (for example, IO, Network, Data, Validation, Authentication). The code is an integer unique within the domain, signaling machine-readable information. The message provides a user-facing explanation, while metadata can include severity, timestamp, stack trace, causality, and localization hints. iError objects are designed to be serializable to formats such as JSON for inter-process communication.

Semantics and usage emphasize stability and portability. Codes should be stable and, where possible, unique within a domain to support deterministic handling. Messages should be localizable, with the machine-readable parts preserving technical details for logs. iError objects can be propagated across asynchronous boundaries and service boundaries while preserving domain and code to aid debugging and automated routing to handlers.

Common examples might include IO:1001 "Read failure," Validation:2002 "Invalid input format," NotFound:3003 "Resource not found," and Auth:4004 "Unauthorized access." A typical representation is a JSON object containing domain, code, message, and optional details such as resource identifiers or stack information. In practice, libraries return iError objects instead of plain exceptions, enabling consistent error handling and user feedback across components.