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:

Error
  └── SDKError
        ├── SDKValidationError
        ├── SDKFormatError
        ├── SDKEncoderError
        ├── SDKExplorerError
        ├── SDKHubError
        ├── SDKConfigError
        ├── SDKContractError
        ├── SDKWalletError
        ├── SDKAuthError
        ├── SDKMessagingError
        └── SDKActionError

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.

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. This runs the full validation and format-selection pipeline but does not call the encoder. It is useful for pre-flight checks in forms or CLI wizards.

try {
    sdk.validateAction({
        action: 'ISSUE',
        params: {
            tick: 'MY.TOKEN',
            maxSupply: 21000000,
            decimals: 8
        }
    });
    console.log('Action is valid — ready to submit');

} catch (err) {
    if (err instanceof SDKValidationError || err instanceof SDKFormatError) {
        console.error('Will not encode:', err.message);
    }
}

validateAction() throws the same SDKValidationError and SDKFormatError instances that createAction() would throw, so the same catch logic applies.

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.