Error Reference

This page is the canonical reference for every error code defined in OIP v0.5. It consolidates the 36 codes into a single matrix, defines the five handling actions, specifies how failures propagate through the three-phase cross-chain coordination, and distinguishes states that look similar at the surface but require different recovery paths. Conformant implementations MUST emit and process all 36 codes listed here.

Sister specification pages introduce the conditions that produce each code in context. Validation defines the eight validation criteria and the sub-checks that fire most of these errors, State Management covers the state-transition family, Cross-chain Protocol covers the divergence and reconciliation flow, and Fault Tolerance covers retry policies, deduplication, and the Dead Letter Queue. This page is the lookup table and the recovery-semantics reference; those pages explain the surrounding logic.

---

Handling Actions

OIP v0.5 defines five handling actions. Every error code maps to exactly one of these, and the mapping is part of the protocol contract: a sender can rely on receiving a deterministic response class for any given code. The five actions partition the failure space into distinct recovery paths.

Figure 1: Handling Actions

The remaining codes fall into silent or automatic categories: DEDUPLICATION_DETECTED is silently ignored as part of idempotency, RECONCILIATION_REQUIRED auto-triggers the reconciliation flow, and MAX_RETRIES_EXCEEDED moves the message into the Dead Letter Queue. ESCALATE is not directly mapped from a single error code; it is the dynamic response invoked by validation logic when an incoming STATE_SYNC resolves to a regulatory-action category, as defined in Validation.

REJECT vs FAILED ACK Distinction

When a node refuses a message, it returns an ACK whose ackType distinguishes the failure mode. The choice carries semantic meaning: REJECTED means the message was structurally or contextually invalid and processing never began, while FAILED means the message was accepted into the pipeline but failed during state evaluation.

This distinction matters for senders building retry logic. A REJECTED response indicates the sender constructed an invalid message and should fix the message itself before resending; a FAILED response indicates the receiver-side state changed (or was inconsistent) and the sender may retry after refreshing local state. Confusing the two leads to retry storms or, conversely, to silently dropped recoverable failures.

interface ErrorAckPayload {
  acknowledgedMessageId: string;
  ackType: "FAILED" | "REJECTED";
  resultCode: string;                      // one of the 36 error codes
  errorDetails: ErrorDetails;
}

interface ErrorDetails {
  errorCode: string;
  errorMessage: string;                    // human-readable description
  retryable: boolean;
  suggestedAction?: "RETRY" | "ROLLBACK" | "ESCALATE" | "ABORT";
  contextData?: object;                    // optional debugging data
}

The retryable flag is the operational shortcut: senders that want simple logic can branch on this single boolean rather than parsing the error code itself. suggestedAction is advisory; final retry policy is governed by the message type’s policy in Fault Tolerance.

The figure below summarizes the decision flow a sender follows on receiving an ACK. Implementations may collapse this into a switch on retryable alone, but the explicit form helps understand why each branch exists.

Figure 2: ACK Handling Decision

Error Code Categories

OIP v0.5 organizes the 36 error codes into seven categories by prefix. The category prefix is a contractual element of the protocol: clients receiving an unknown code SHOULD fall back to category-level handling rather than rejecting the entire ACK. This is the foundation of forward compatibility (see Extension Policy).

Figure 3: Category Distribution

Authority

Errors raised when a message claims regulatory authority that the receiver cannot verify. All four codes REJECT with non-retryable semantics: the sender’s authority claim itself is wrong, and resending the same claim cannot succeed. These checks fire during validation criterion (3) authority verification, before any state mutation is attempted.

State Transition

Errors raised when a state transition violates the matrix in State Management or when a postcondition fails after partial execution. The Escalation Chain errors (FREEZE_REQUIRED_BEFORE_SEIZE, SEIZE_REQUIRED_BEFORE_CONFISCATE) enforce the legally required ordering of regulatory actions and are non-retryable until the sender first applies the missing predecessor action.

STATE_HASH_MISMATCH uses FAILED rather than REJECTED because the message itself was structurally valid; only the receiver-side state diverged. Senders should refresh local state from the receiver and resend with the updated hash. The two POSTCONDITION_VIOLATION_* codes differ in scope: see the dedicated POSTCONDITION_VIOLATION Single vs Multi section below for the rollback-sequence comparison.

Legal Basis

Errors raised when the legal documentation accompanying a regulatory action is structurally invalid, expired, or premature. APPEAL_PERIOD_NOT_EXPIRED guards CONFISCATE specifically: a confiscation cannot proceed before the asset’s appeal window has closed.

APPEAL_PERIOD_NOT_EXPIRED and LEGAL_BASIS_EXPIRED_OR_NOT_YET_VALID are time-variant errors: the same message may succeed at a different point in time. See Time-Variant Errors and Retry Semantics for the retry timing model.

Cross-chain

Errors that arise when the system detects inconsistency across chains or when a target chain cannot fulfill an atomicity requirement. Most codes in this category surface during the COMMIT phase of three-phase coordination; see Phase-Level Failure Semantics for the exact mapping. The DIVERGE family (CROSS_CHAIN_STATE_CONFLICT, DIVERGED_STATE_DETECTED) is qualitatively distinct from REJECT: rather than refusing a single message, it pauses the entire asset until reconciliation completes.

RECONCILIATION_REQUIRED is the only code in the entire reference that is not sender-facing: it is an internal signal a node emits to itself or to peer nodes to trigger the reconciliation flow. Senders never receive this code in an ACK. DIVERGED state and ROLLBACK_INCOMPLETE state look superficially similar but represent different recovery paths; see DIVERGED vs ROLLBACK_INCOMPLETE for the comparison.

Address

Errors raised during address resolution. The OIP OIPAddress format combines ERC-3770 short names with CAIP-2 chain identifiers; any failure in this resolution chain produces one of these four codes. Address-resolution checks run before authority verification because an unresolvable address makes downstream authority lookup impossible.

INVALID_ADDRESS_CHECKSUM applies only to mixed-case addresses; lowercase or fully uppercase addresses bypass checksum validation per EIP-55. Senders should always emit mixed-case addresses to benefit from the typo-detection guarantee.

Delivery

Errors related to message lifecycle and transport. This category contains the only RETRY code (DELIVERY_TIMEOUT) and the only DLQ code (MAX_RETRIES_EXCEEDED) in the entire reference. The full delivery model, including retry policies per message type and the DLQ recovery protocol, lives in Fault Tolerance.

DEDUPLICATION_DETECTED is silently ignored as part of OIP's idempotency contract: detecting a duplicate is a normal operational event, not a failure, and the sender already received the original ACK. Generating a new ACK for the duplicate would itself violate idempotency.

Message Integrity

The largest category. These eight codes cover every aspect of cryptographic verification, attestation validation, and replay protection. Three of these codes apply only to messages originating from Canton via a Canton Driver; see CANTON-Specific Codes for the dedicated subset. Two codes (INVALID_SIGNATURE, INVALID_THRESHOLD_SIGNATURE) are flagged for slashing review when the failure pattern suggests malicious behavior; see Slashing-Eligible Codes.

ATTESTATION_REPLAY_DETECTED closes a specific replay vector that DEDUPLICATION_DETECTED alone cannot catch: the same Canton transaction wrapped in two different OIP messages with different messageId values would pass the messageId dedup check but fail this one.

Phase-Level Failure Semantics

Cross-chain messages travel through a three-phase staged coordination: PREPARE, COMMIT, FINALIZE, defined in Cross-chain Protocol. Each phase has its own failure semantics: which errors can fire, what side effects roll back, and what the lock holds. This section is the recovery-semantics reference for cross-chain operations.

Figure 4: Phase-Level Failure Semantics

PREPARE Failure

The preemptive lock is acquired at the start of PREPARE. If validation fails inside PREPARE, the abort path releases the lock immediately. During a retry attempt, the lock is held to prevent racing transactions from acquiring it; if all retries fail, the lock is held until its TTL expires, at which point it is released automatically. This behavior aligns with the lock-timeout safety property of the Preemptive Lock Correctness verification.

COMMIT Failure

COMMIT failures are the most consequential because state has already changed on at least one chain when the failure is detected. Two distinct failure modes arise: cross-chain state conflict (some chains saw the change, others did not, or one rejected it) and intentional rollback in progress. The protocol distinguishes these by transitioning to either DIVERGED or ROLLBACK_INCOMPLETE; see the next section for the comparison.

FINALIZE Failure

FINALIZE is the lock-release signal. Failures here are treated conservatively: the state change is NOT rolled back. The reasoning is that FINALIZE failure is a "confirmation failure," not a "state-change failure." Rolling back a successfully committed state because the confirmation message was lost would create more risk than it solves: a transient network glitch could invalidate legitimate transactions. Instead, chains that did not receive FINALIZE keep their lock held until TTL expires, at which point it is released automatically.

DIVERGED vs ROLLBACK_INCOMPLETE

These two states look similar at the surface but are produced by different causes and have different recovery paths. Confusing them in operations leads to applying the wrong recovery procedure. The protocol intentionally separates them so that automatic systems can route based on the state alone, without having to inspect the underlying error code.

Figure 5: DIVERGED vs ROLLBACK_INCOMPLETE

The cleanest way to think about the difference: DIVERGED is "we don't know which chain is right yet", while ROLLBACK_INCOMPLETE is "we know what should happen but haven't finished doing it". Reconciliation discovers the truth; governance enforces it.

POSTCONDITION_VIOLATION Single vs Multi

POSTCONDITION_VIOLATION_SINGLE and POSTCONDITION_VIOLATION_MULTI share the same prefix and the same handling action (ROLLBACK), but their operational consequences differ by an order of magnitude. The single-chain variant triggers a local rollback on one chain; the multi-chain variant triggers an ALL_OR_NOTHING rollback sequence across every chain involved in the transaction.

The retryable: false on the multi-chain variant is not a permanent rejection. It signals that the specific in-flight sequence has been fully unwound; senders construct a new sequence with a new messageId rather than resending the failed one. This avoids races between the rollback completion and an immediate retry.

Time-Variant Errors and Retry Semantics

Three error codes have outcomes that change with the passage of time. The same message that fails now may succeed at a later point, without any change to the message itself. Senders must understand the timing model for each, because retry-too-early just produces another failure, and retry-too-late may run into TTL expiration.

Implementations SHOULD attach the relevant timestamp (issuedAt, appealDeadline) to errorDetails.contextData so that automated retry schedulers can compute the correct retry time without consulting external sources. The protocol does not require this, but the operational benefit is substantial.

Slashing-Eligible Codes

Two error codes mark failures that may indicate malicious behavior rather than transient corruption. When the failure pattern (frequency, source, correlation across messages) suggests deliberate misbehavior, these codes are flagged for slashing review at the consensus layer. The slashing decision itself is governed by the consensus layer, not by the protocol message; the error code is a signal, not a slashing trigger.

Other Message Integrity codes (INVALID_HEADER_FORMAT, INVALID_SOURCE_AUTHENTICATION, etc.) do not directly imply malicious intent: they are typically caused by software bugs, version skew, or relayer errors. A node receiving these codes simply rejects the message; there is no slashing review path.

CANTON-Specific Codes

Four codes apply only to messages originating from Canton via a Canton Driver. EVM-originated messages never produce these codes. The codes form a contiguous subset of the Message Integrity category and reflect the additional verification surface introduced by the Canton attestation model.

Implementations that do not integrate with Canton can omit the validation logic for these codes (no Canton-originated messages will ever reach them), but they MUST still emit these codes correctly if they observe a malformed or replayed Canton attestation. Forward compatibility requires the codes to be present in every conformant implementation's vocabulary, even when the implementation never produces them in practice.

Complete Error Code Matrix

The full matrix of all 36 codes in a single table, sorted by category and code number. This is the canonical lookup table for implementations. The Retryable column reflects the retryable flag in ErrorDetails; conditional values are explained inline.

Validation Criteria Mapping

The eight validation criteria defined in Validation map to specific error codes. Implementations can use this table to localize a failure: knowing the failing criterion narrows the diagnostic surface to a small set of codes.

INVALID_STATE_TRANSITION appears under both criterion (4) and criterion (5) because the same code is emitted when the transition is undefined in the matrix (precondition view) and when applying it would break a state invariant (postcondition view). Implementations may attach a contextData.subCriterion hint to disambiguate, but the protocol does not require it.

Extension Policy

OIP v0.5 defines exactly 36 error codes. Future versions may add new codes under the following rules.

• Category prefix consistency: a new code MUST belong to one of the seven existing categories. Introducing a new category requires a major version increase.
• Major version change: changing the meaning of an existing code is a breaking change and triggers a major version increase.
• Minor version change: adding new codes within existing categories is non-breaking and triggers a minor version increase.
• Forward compatibility: clients receiving an unknown error code SHOULD fall back to category-level handling based on the prefix. For example, an unknown STATE_* code should be treated as a state-transition family error, applying the closest known recovery path.

The forward-compatibility rule is the practical reason every code carries a meaningful prefix. A v0.5 client interoperating with a v0.6 implementation may encounter STATE_NEW_CONDITION_FOO; the prefix lets it route the failure into its existing state-transition handler rather than crashing or treating the message as unknown garbage. During the v0.x phase (before v1.0), even minor version changes can be incompatible; clients should not rely on forward compatibility as a substitute for version negotiation.

---

References

• EIP-55: Mixed-case checksum address encoding
• ERC-3770: Chain-specific addresses
• CAIP-2: Blockchain ID specification
• RFC 2119: Key words for use in RFCs to indicate requirement levels

Related Pages

• Validation: the eight validation criteria and processing pipelines that emit these codes
• State Management: state transition matrix and Escalation Chain rules
• Cross-chain Protocol: PREPARE/COMMIT/FINALIZE staged coordination and reconciliation flow
• Fault Tolerance: retry policies, deduplication, DLQ recovery protocol
• Regulatory Actions: Escalation Chain and CONFISCATE appeal window