XChain Platform SDK: Error Reference

This document covers all error classes thrown by the XChain Platform SDK, their codes, and how to handle them in application code.

Error Hierarchy

All SDK errors extend a common base class:

flowchart TD
    ERR["Error"]
    SDKERR["SDKError"]
    VAL["SDKValidationError"]
    FMT["SDKFormatError"]
    ENC["SDKEncoderError"]
    EXP["SDKExplorerError"]
    HUB["SDKHubError"]
    CFG["SDKConfigError"]
    CONTRACT["SDKContractError"]
    WALLET["SDKWalletError"]
    AUTH["SDKAuthError"]
    MSG["SDKMessagingError"]
    ACTION["SDKActionError"]
    MUSIG["SDKMuSigError"]
    GATED["SDKGatedFileError"]
    POLICY["SDKPolicyError"]
    X402["SDKX402Error"]

    ERR --> SDKERR
    SDKERR --> VAL
    SDKERR --> FMT
    SDKERR --> ENC
    SDKERR --> EXP
    SDKERR --> HUB
    SDKERR --> CFG
    SDKERR --> CONTRACT
    SDKERR --> WALLET
    SDKERR --> AUTH
    SDKERR --> MSG
    SDKERR --> ACTION
    SDKERR --> MUSIG
    SDKERR --> GATED
    SDKERR --> POLICY
    SDKERR --> X402

Every error instance carries four properties:

Error Classes

Error Codes Reference

SDKValidationError

Thrown during action validation before any network call is made.

SDKFormatError

Thrown by the format selector when it cannot choose a format version for the action.

SDKEncoderError

Thrown when communication with the xchain-encoder service fails.

SDKExplorerError

Thrown when communication with the xchain-explorer service fails.

SDKHubError

Thrown when the xchain-hub config oracle cannot be reached.

SDKConfigError

Thrown at call time when a required service URL has not been configured.

SDKContractError

Thrown for contract-specific issues during DEPLOY, EXECUTE, DEPOSIT, or WITHDRAW operations.

SDKWalletError

Thrown by wallet operations: key management, address derivation, PSBT signing, transaction broadcasting, and UTXO queries.

SDKAuthError

Thrown by authentication operations: challenge generation, message signing, and signature verification setup errors. Note: verifyOwnership and verifyMessage return { valid: false } instead of throwing.

SDKMessagingError

Thrown by messaging operations: encryption, decryption, public key lookup, and message sending.

SDKActionError

Thrown by the action waiter (ActionWaiter) when waiting for a broadcast transaction to be indexed.

SDKPolicyError

Thrown by AgentSession.submit() when a declarative spending policy check fails, or during construction when the policy object is invalid. See Agent Wallets.

SDKX402Error

Thrown by the X402Gateway and X402Client during HTTP 402 payment flows. See src/x402.js.

Catching Errors

Import the error classes you need and use instanceof checks in your catch block. Check error.code for fine-grained handling and error.details for additional context.

const {
    SDKValidationError,
    SDKFormatError,
    SDKEncoderError,
    SDKConfigError,
    SDKContractError,
    SDKWalletError,
    SDKAuthError
} = require('@xchain/sdk/src/errors');

try {
    let result = await sdk.createAction({
        action: 'SEND',
        params: { tick: 'DOGE.TOKEN', amount: 100, destination: 'abc123' }
    });
    console.log(result.actionString);

} catch (err) {

    if (err instanceof SDKValidationError) {
        // Input was rejected before any network call
        console.error('Validation failed:', err.code, err.message);

        if (err.code === 'MISSING_REQUIRED_FIELD') {
            console.error('Missing field:', err.details.field);
        }
        if (err.code === 'INVALID_FIELD_VALUE') {
            console.error('Bad value for', err.details.field, ':', err.details.value);
            console.error('Constraint:', err.details.constraint);
        }
        if (err.code === 'BATCH_CONSTRAINT') {
            console.error('BATCH rule violated:', err.message);
        }

    } else if (err instanceof SDKFormatError) {
        // No format version fits the provided fields
        console.error('Format selection failed:', err.code);

        if (err.code === 'NO_MATCHING_FORMAT') {
            console.error('Provided fields:', err.details.populatedFields);
            console.error('Available formats:', JSON.stringify(err.details.availableFormats, null, 2));
        }

    } else if (err instanceof SDKEncoderError) {
        // Encoder RPC or network problem
        console.error('Encoder error:', err.code, err.message);

    } else if (err instanceof SDKConfigError) {
        // Service URL not configured
        console.error('Configuration error:', err.code);

    } else if (err instanceof SDKContractError) {
        // Contract-specific error (code too large, bad hex, etc.)
        console.error('Contract error:', err.code, err.message);

    } else if (err instanceof SDKWalletError) {
        // Wallet operation failed (key import, PSBT signing, broadcast, etc.)
        console.error('Wallet error:', err.code, err.message);

    } else if (err instanceof SDKAuthError) {
        // Auth operation failed (challenge generation, message signing)
        console.error('Auth error:', err.code, err.message);

    } else if (err instanceof SDKMessagingError) {
        // Messaging operation failed (encryption, decryption, pubkey lookup)
        console.error('Messaging error:', err.code, err.message);

    } else if (err instanceof SDKActionError) {
        // Transaction lifecycle failure (confirmation timeout, action rejected by indexer)
        console.error('Action error:', err.code, err.message);
        if (err.code === 'CONFIRMATION_TIMEOUT') {
            console.error('Transaction was broadcast but not indexed within timeout');
        }
        if (err.code === 'ACTION_REJECTED') {
            console.error('Action was indexed but marked invalid:', err.details.reason);
        }

    } else {
        // Unexpected error; rethrow
        throw err;
    }
}

Validation Dry-Run

Use sdk.validateAction() to check an action’s fields before constructing a transaction. It runs the validation pipeline but does not call the encoder and does not throw. It is useful for pre-flight checks in forms or CLI wizards.

const result = sdk.validateAction('ISSUE', {
    tick: 'MY.TOKEN',
    maxSupply: 21000000,
    decimals: 8
});

if (result.valid) {
    console.log('Action is valid; ready to submit');
} else {
    console.error('Will not encode:', result.errors);
    // result.errors is an array of { code, message, details } objects
}

validateAction(action, params) takes the action name as the first argument and the params object as the second. It always returns { valid, errors } and never throws.

Copyright © 2025–2026 Dankest, LLC

Based on XChain Platform by Dankest, LLC – https://dankest.llc

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later) with a commercial license available for proprietary use.

You may use, modify, and distribute this material under the terms of the License. See LICENSE and NOTICE for full terms. See the licensing overview.