Error Codes

All x0 error codes follow a structured numbering scheme for easy identification:

Range	Program	Domain
`0x1100–0x114F`	x0-guard	Policy, transfer, and Blink errors
`0x1108–0x121F`	x0-escrow	Escrow state and operation errors
`0x1300–0x130F`	x0-registry	Agent registration errors
`0x1400–0x140F`	x0-reputation	Reputation tracking errors
`0x1500–0x1515`	x0-token	Token and confidential transfer errors
`0x1600–0x164F`	x0-wrapper	Wrapper, reserve, and governance errors
`0x1700–0x1721`	x0-zk-verifier	Proof verification errors

Within each category, subcategories follow a consistent pattern:

Low nibble range	Subcategory
`0xNN00–0xNN0F`	Core / fundamental errors
`0xNN10–0xNN1F`	Configuration errors
`0xNN20–0xNN2F`	State transition errors
`0xNN30–0xNN3F`	Validation errors
`0xNN40–0xNN4F`	Authorization errors
`0xNN50–0xNN5F`	Rate limiting errors

X0GuardError

Policy Errors (0x1100)

Code	Name	Message
`0x1101`	`RecipientNotWhitelisted`	Recipient not whitelisted
`0x1102`	`DailyLimitExceeded`	Daily spending limit exceeded
`0x1103`	`InvalidMerkleProof`	Invalid Merkle proof
`0x1104`	`InvalidBloomFilter`	Invalid Bloom filter configuration
`0x1105`	`PolicyNotFound`	Agent policy not found
`0x1106`	`UnauthorizedSigner`	Unauthorized signer
`0x1107`	`ConfidentialTransferFailed`	Confidential transfer proof verification failed

Policy Configuration Errors (0x1110)

Code	Name	Message
`0x1110`	`DailyLimitTooHigh`	Daily limit exceeds maximum
`0x1111`	`DailyLimitTooLow`	Daily limit below minimum
`0x1112`	`InvalidWhitelistConfig`	Invalid whitelist configuration
`0x1113`	`MissingMerkleProof`	Missing Merkle proof
`0x1114`	`PolicyAlreadyInitialized`	Policy already initialized
`0x1115`	`PolicyOwnerMismatch`	Policy owner mismatch
`0x1116`	`AgentSignerActive`	Agent signer already active
`0x1117`	`RollingWindowOverflow`	Rolling window overflow
`0x1118`	`DelegationRequired`	Delegation required: agent must be delegate, not owner
`0x1119`	`TokenAccountOwnerMismatch`	Token account owner must match policy owner
`0x111A`	`SelfDelegationNotAllowed`	Self-delegation not allowed
`0x111B`	`BoundTokenAccountMismatch`	Transfer must originate from bound token account
`0x111C`	`InvalidTokenAccountData`	Invalid token account data
`0x111D`	`InvalidZkProofOwner`	ZK proof account must be owned by Token-2022 program
`0x111E`	`ZkProofContextMismatch`	ZK proof context does not match transfer parameters
`0x111F`	`MissingZkProof`	ZK proof required for confidential transfer

Transfer Errors (0x1120)

Code	Name	Message
`0x110A`	`InsufficientFunds`	Insufficient funds
`0x1120`	`ZeroTransferAmount`	Transfer amount cannot be zero
`0x1121`	`TransferAmountTooHigh`	Transfer amount exceeds maximum
`0x1122`	`InvalidMemoHash`	Invalid memo hash
`0x1123`	`InvalidTimestamp`	Invalid timestamp

Blink Errors (0x1130)

Code	Name	Message
`0x1130`	`BlinkRateLimitExceeded`	Blink rate limit exceeded
`0x1131`	`BlinkExpired`	Blink expired
`0x1132`	`InvalidBlinkSignature`	Invalid Blink signature
`0x1133`	`BlinkAlreadyProcessed`	Blink already processed

Medium Severity Errors (0x1140)

Code	Name	Message
`0x1140`	`PolicyUpdateTooFrequent`	Policy updates are rate limited — try again later
`0x1141`	`SingleTransactionLimitExceeded`	Transaction exceeds single transaction limit
`0x1142`	`TransferAmountTooSmall`	Transfer amount below minimum threshold
`0x1143`	`ExtraMetasAlreadyInitialized`	Extra account metas already initialized
`0x1144`	`UnauthorizedExtraMetasInitializer`	Only the mint authority can initialize extra account metas

X0EscrowError

State Errors (0x1108)

Code	Name	Message
`0x1108`	`EscrowExpired`	Escrow timeout reached
`0x1109`	`InvalidEscrowState`	Invalid escrow state for this operation

Configuration Errors (0x1200)

Code	Name	Message
`0x1200`	`EscrowTimeoutTooShort`	Escrow timeout too short
`0x1201`	`EscrowTimeoutTooLong`	Escrow timeout too long
`0x1202`	`SameBuyerAndSeller`	Buyer and seller must be different
`0x1203`	`InvalidArbiter`	Invalid arbiter
`0x1204`	`ZeroEscrowAmount`	Escrow amount cannot be zero
`0x1205`	`EscrowAlreadyExists`	Escrow already exists
`0x1206`	`InvalidMint`	Invalid mint account

Operation Errors (0x1210)

Code	Name	Message
`0x1210`	`OnlyBuyerCanFund`	Only buyer can fund escrow
`0x1211`	`OnlySellerCanDeliver`	Only seller can mark as delivered
`0x1212`	`OnlyBuyerCanRelease`	Only buyer can release funds
`0x1213`	`OnlyArbiterCanResolve`	Only arbiter can resolve dispute
`0x1214`	`InvalidEvidenceHash`	Invalid evidence hash
`0x1215`	`DisputeAlreadyInitiated`	Dispute already initiated
`0x1216`	`CannotDisputeBeforeDelivery`	Cannot dispute before delivery
`0x1217`	`ArbiterResolutionTooEarly`	Arbiter must wait for resolution delay period
`0x1218`	`DisputeEvidenceRequired`	Dispute evidence required before arbiter resolution

X0RegistryError

Code	Name	Message
`0x1300`	`AgentAlreadyRegistered`	Agent already registered
`0x1301`	`AgentNotFound`	Agent not found
`0x1302`	`InvalidEndpoint`	Invalid endpoint URL
`0x1303`	`EndpointTooLong`	Endpoint too long
`0x1304`	`TooManyCapabilities`	Too many capabilities
`0x1305`	`InvalidCapabilityType`	Invalid capability type
`0x1306`	`CapabilityMetadataTooLong`	Capability metadata too long
`0x1307`	`InsufficientListingFee`	Insufficient listing fee
`0x1308`	`UnauthorizedRegistryUpdate`	Unauthorized registry update
`0x1309`	`RegistryEntryExpired`	Registry entry expired

X0ReputationError

Code	Name	Message
`0x1400`	`ReputationNotFound`	Reputation account not found
`0x1401`	`ReputationAlreadyInitialized`	Reputation already initialized
`0x1402`	`InvalidReputationUpdate`	Invalid reputation update
`0x1403`	`UnauthorizedReputationUpdate`	Unauthorized reputation update
`0x1404`	`InsufficientTransactions`	Insufficient transactions for reputation
`0x1405`	`ReputationScoreOutOfRange`	Reputation score out of range
`0x1406`	`InvalidPolicyAccount`	Invalid policy account
`0x1407`	`Unauthorized`	Unauthorized

X0TokenError

Token Errors (0x1500)

Code	Name	Message
`0x1500`	`MintAlreadyInitialized`	Mint already initialized
`0x1501`	`InvalidMintAuthority`	Invalid mint authority
`0x1502`	`InvalidTransferHookProgram`	Invalid transfer hook program
`0x1503`	`ConfidentialTransfersNotEnabled`	Confidential transfers not enabled
`0x1504`	`InvalidTokenDecimals`	Invalid token decimals
`0x1505`	`TransferHookValidationFailed`	Transfer hook validation failed

Confidential Transfer Errors (0x1506)

Code	Name	Message
`0x1506`	`AccountNotConfiguredForConfidential`	Account not configured for confidential transfers
`0x1507`	`InvalidElGamalPubkey`	Invalid ElGamal public key
`0x1508`	`InvalidPubkeyValidityProof`	Invalid pubkey validity proof
`0x1509`	`InvalidZeroCiphertextProof`	Invalid zero ciphertext proof
`0x150A`	`InvalidWithdrawProof`	Invalid withdraw proof
`0x150B`	`ConfidentialBalanceInsufficient`	Confidential balance insufficient
`0x150C`	`PendingBalanceNotApplied`	Pending balance must be applied before this operation
`0x150D`	`MaxPendingBalanceCreditsExceeded`	Maximum pending balance credit counter exceeded
`0x150E`	`ConfidentialCreditsDisabled`	Confidential credits are disabled on this account
`0x150F`	`AmountExceedsConfidentialMax`	Amount exceeds maximum for confidential transfers (2^48 - 1)
`0x1510`	`ProofContextMismatch`	Proof context account does not match expected
`0x1511`	`ProofVerificationFailed`	Zero-knowledge proof verification failed
`0x1512`	`AuditorPubkeyRequired`	Auditor ElGamal pubkey is required for this operation
`0x1513`	`NonConfidentialCreditsDisabled`	Non-confidential credits are disabled on this account
`0x1514`	`AccountAlreadyConfigured`	Account is already configured for confidential transfers
`0x1515`	`InvalidDecryptableBalance`	Invalid decryptable balance ciphertext format

X0WrapperError

State Errors (0x1600)

Code	Name	Message
`0x1600`	`WrapperPaused`	Wrapper operations are paused
`0x1601`	`WrapperAlreadyInitialized`	Wrapper already initialized
`0x1602`	`WrapperNotInitialized`	Wrapper not initialized
`0x1603`	`InvalidUsdcMint`	Invalid USDC mint address
`0x1604`	`InvalidWrapperMint`	Invalid wrapper mint address
`0x1605`	`DecimalMismatch`	Token decimal mismatch
`0x1606`	`InvalidMintConfiguration`	Invalid mint configuration

Reserve & Invariant Errors (0x1610)

Code	Name	Message
`0x1610`	`InsufficientReserve`	Insufficient reserve balance
`0x1611`	`ReserveInvariantViolated`	Reserve invariant violated: reserve < supply
`0x1612`	`ReserveRatioWarning`	Reserve ratio below warning threshold
`0x1613`	`ReserveRatioCritical`	Reserve ratio critical: undercollateralized

Amount & Fee Errors (0x1620)

Code	Name	Message
`0x1620`	`DepositTooSmall`	Deposit amount below minimum
`0x1621`	`RedemptionTooSmall`	Redemption amount below minimum
`0x1622`	`RedemptionTooLarge`	Redemption exceeds per-transaction limit
`0x1623`	`DailyRedemptionLimitExceeded`	Daily redemption limit exceeded
`0x1624`	`FeeRateTooHigh`	Fee rate exceeds maximum allowed
`0x1625`	`FeeRateTooLow`	Fee rate below minimum allowed
`0x1626`	`MathOverflow`	Math overflow in calculation
`0x1627`	`MathUnderflow`	Math underflow in calculation

Authorization Errors (0x1630)

Code	Name	Message
`0x1630`	`Unauthorized`	Unauthorized: admin required
`0x1631`	`InvalidMultisig`	Invalid multisig configuration
`0x1632`	`NoPendingAdminTransfer`	No pending admin transfer
`0x1633`	`NotPendingAdmin`	Caller is not the pending admin

Timelock Errors (0x1640)

Code	Name	Message
`0x1640`	`AdminActionNotFound`	Admin action not found
`0x1641`	`AdminActionAlreadyExecuted`	Admin action already executed
`0x1642`	`AdminActionCancelled`	Admin action was cancelled
`0x1643`	`TimelockNotExpired`	Timelock period not yet expired
`0x1644`	`TimelockExpired`	Timelock period has expired
`0x1645`	`InvalidActionType`	Invalid admin action type

X0ZkVerifierError

Proof Verification Errors (0x1700)

Code	Name	Message
`0x1700`	`ProofVerificationFailed`	Zero-knowledge proof verification failed
`0x1701`	`InvalidProofData`	Invalid proof data format
`0x1702`	`ProofContextExists`	Proof context already exists
`0x1703`	`InvalidProofType`	Invalid proof type
`0x1704`	`ProofExpired`	Proof has expired

Parameter Validation Errors (0x1710)

Code	Name	Message
`0x1710`	`AmountTooLarge`	Amount exceeds maximum (2^48 - 1)
`0x1711`	`InvalidElGamalPubkey`	Invalid ElGamal public key
`0x1712`	`InvalidCiphertext`	Invalid ciphertext format
`0x1713`	`ProofSizeMismatch`	Proof data size does not match expected size
`0x1714`	`RecipientMismatch`	Recipient does not match proof context
`0x1715`	`AmountMismatch`	Amount does not match proof context

Math Errors (0x1720)

Code	Name	Message
`0x1720`	`ArithmeticOverflow`	Arithmetic overflow in calculation
`0x1721`	`ArithmeticUnderflow`	Arithmetic underflow in calculation

Unified X0Error

For cross-program invocations, errors are wrapped in a unified type:

pub enum X0Error {
    Guard(X0GuardError),
    Escrow(X0EscrowError),
    Registry(X0RegistryError),
    Reputation(X0ReputationError),
    Token(X0TokenError),
    Wrapper(X0WrapperError),
}

Handling Errors in the SDK

import { AnchorError } from '@coral-xyz/anchor';

try {
  await client.transfer(recipient, amount);
} catch (err) {
  if (err instanceof AnchorError) {
    switch (err.error.errorCode.code) {
      case 'DailyLimitExceeded':
        // Generate a Blink for human approval
        break;
      case 'RecipientNotWhitelisted':
        // Recipient not in policy whitelist
        break;
      default:
        console.error(`Error ${err.error.errorCode.number}: ${err.error.errorMessage}`);
    }
  }
}

Overview

Core Programs

Zero-Knowledge

Application Layer

Reference

X0GuardError

Policy Errors (0x1100)

Policy Configuration Errors (0x1110)

Transfer Errors (0x1120)

Blink Errors (0x1130)

Medium Severity Errors (0x1140)

X0EscrowError

State Errors (0x1108)

Configuration Errors (0x1200)

Operation Errors (0x1210)

X0RegistryError

X0ReputationError

X0TokenError

Token Errors (0x1500)

Confidential Transfer Errors (0x1506)

X0WrapperError

State Errors (0x1600)

Reserve & Invariant Errors (0x1610)

Amount & Fee Errors (0x1620)

Authorization Errors (0x1630)

Timelock Errors (0x1640)

X0ZkVerifierError

Proof Verification Errors (0x1700)

Parameter Validation Errors (0x1710)

Math Errors (0x1720)

Unified X0Error

Handling Errors in the SDK

Overview

Core Programs

Zero-Knowledge

Application Layer

Reference

​X0GuardError

​Policy Errors (0x1100)

​Policy Configuration Errors (0x1110)

​Transfer Errors (0x1120)

​Blink Errors (0x1130)

​Medium Severity Errors (0x1140)

​X0EscrowError

​State Errors (0x1108)

​Configuration Errors (0x1200)

​Operation Errors (0x1210)

​X0RegistryError

​X0ReputationError

​X0TokenError

​Token Errors (0x1500)

​Confidential Transfer Errors (0x1506)

​X0WrapperError

​State Errors (0x1600)

​Reserve & Invariant Errors (0x1610)

​Amount & Fee Errors (0x1620)

​Authorization Errors (0x1630)

​Timelock Errors (0x1640)

​X0ZkVerifierError

​Proof Verification Errors (0x1700)

​Parameter Validation Errors (0x1710)

​Math Errors (0x1720)

​Unified X0Error

​Handling Errors in the SDK

X0GuardError

Policy Errors (0x1100)

Policy Configuration Errors (0x1110)

Transfer Errors (0x1120)

Blink Errors (0x1130)

Medium Severity Errors (0x1140)

X0EscrowError

State Errors (0x1108)

Configuration Errors (0x1200)

Operation Errors (0x1210)

X0RegistryError

X0ReputationError

X0TokenError

Token Errors (0x1500)

Confidential Transfer Errors (0x1506)

X0WrapperError

State Errors (0x1600)

Reserve & Invariant Errors (0x1610)

Amount & Fee Errors (0x1620)

Authorization Errors (0x1630)

Timelock Errors (0x1640)

X0ZkVerifierError

Proof Verification Errors (0x1700)

Parameter Validation Errors (0x1710)

Math Errors (0x1720)

Unified X0Error

Handling Errors in the SDK