Error Handling
ALX Protocol defines canonical ALX_* error identifiers in the published error code registry. Each SDK reports a failed protocol operation with the matching identifier, using language-appropriate result and error types.
Error Identifiers
The core registry assigns each identifier a category, such as schema, hash, graph, or canonicalization, and a severity. Extension identifiers are published in the Merkle extension registry and the signing extension registry.
Result Model
Successful operations return the values produced by the protocol operation. A hash mismatch is a validation result, not an error. Every SDK starts a protocol failure message with the identifier in brackets, for example [ALX_INVALID_HASH] invalid hash: 0x1234. Read the identifier from that prefix. Strict JSON parsing reports malformed JSON, duplicate members, and trailing data without an identifier: a SyntaxError in TypeScript, a ValueError in Python, and an Err(String) in Rust. An application that reports an identifier for these failures uses ALX_SCHEMA_INVALID.
| SDK | Failed operation | Block validation result |
|---|---|---|
| TypeScript | Throws an Error; the identifiers are exported as ErrorCode | An object with ok: false |
| Python | Raises ValueError | A dictionary with "ok": False |
| Rust | Returns Err(String) | A BlockValidation with ok: false from validate_block_detailed() |
Language References
Each SDK reference lists the package, installation, and capabilities:
When to Handle Errors
Inspect the selected SDK contract before accepting validation results or processing untrusted input. Keep application transport, authorization, and recovery errors separate from protocol operation results.