Runtime errors
Structured failure stages, categories, symbolic codes, retryability, and safe handling.
The Axiom Runtime represents a failed operation as a structured AxiomError.
Framework bindings can change naming conventions during serialization, but the
semantic fields are:
| Field | Meaning |
|---|---|
stage | Pipeline boundary where the failure occurred |
category | Broad class used for UI, metrics, and policy |
code | Specific symbolic condition; an HTTP status can carry its number |
message | Human-oriented summary safe for application handling |
retryable | Runtime assessment of whether another attempt may succeed |
details | Optional additional context |
source | Optional internal source context; bindings may omit it |
Do not parse message to make control-flow decisions. Match the typed or
serialized code, and preserve an unknown fallback so a newer runtime does not
break an older UI.
Stages
| Stage | Boundary |
|---|---|
Configuration | Runtime or contract configuration |
ContractLoad | Artifact loading or validation |
RequestBuild | Endpoint lookup, path, headers, or body construction |
ValidationRequest | Outbound value did not satisfy the contract |
CacheRead | Reading a configured cache |
NetworkSend | Establishing or sending the request |
NetworkReceive | Receiving transport or HTTP response data |
ValidationResponse | Inbound value did not satisfy the contract |
Deserialize | JSON or codec decoding |
CacheWrite | Persisting a response cache entry |
Runtime | Engine lifecycle or internal execution |
FfiBoundary | Native/Wasm binding boundary |
Serialized clients can expose lower-camel-case equivalents. Confirm the actual binding type rather than hard-coding display text.
Categories
Contract, Validation, Network, Timeout, Serialization, Cache,
Auth, Server, Runtime, and Unknown are the current runtime categories.
A category is intentionally broader than the code: for example, several HTTP
statuses can map to Auth or Server behavior.
Symbolic codes
| Group | Codes |
|---|---|
| Contract | ContractMissing, ContractInvalid, EndpointNotFound |
| Request | RequestCreationError, PayloadEncodingError |
| Validation | ValidationError |
| Network | NetworkConnectionFailed, NetworkTimeout, HttpStatus(status) |
| Data | JsonParseError, CodecError |
| Cache | CacheReadError, CacheWriteError |
| Authentication | AuthTokenMissing, AuthTokenExpired |
| Runtime | NotInitialized, InternalError |
Numeric FFI status values are a lower-level compatibility boundary and can collapse several symbolic codes. Application code should use the structured error emitted by its binding rather than copying a numeric table.
Handling pattern
function messageFor(error: AxiomError): string {
if (error.category === 'Auth') return 'Please sign in again.';
if (error.retryable) return 'Request failed. Try again.';
if (error.code === 'ContractInvalid') {
return 'This application release has an invalid data contract.';
}
return 'Something went wrong.';
}The exact enum casing in generated TypeScript or Dart is authoritative. Keep detailed diagnostic context in protected logs, not in a user-visible message.
Retry guidance
- retry only when the error says it is retryable or application policy explicitly permits it;
- cap attempts and add jitter for network retries;
- do not retry an invalid contract, unknown endpoint, request validation, or deterministic decoding failure without changing input or deployment;
- refresh or clear credentials before retrying an authentication failure; and
- treat cache errors separately from network success so a write failure does not masquerade as a failed server operation.