> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x0protocol.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Complete reference of all error codes across the x0 protocol, organized by program and category.

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:

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

## Handling Errors in the SDK

```typescript theme={null}
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}`);
    }
  }
}
```