Error Handling

The SDK provides typed errors for robust error handling.

Error Types

import {
  OpenClawWalletError,
  ConfigurationError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NetworkError,
  InsufficientFundsError,
} from '@loomlay/openclaw-wallet-sdk';

Basic Error Handling

try {
  await wallet.trading.swap({
    inputToken: 'SOL',
    outputToken: 'USDC',
    amount: '100',
  });
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.log('Not enough SOL:', error.message);
    console.log('Required:', error.required);
    console.log('Available:', error.available);
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited. Retry after:', error.retryAfter, 'seconds');
  } else if (error instanceof ValidationError) {
    console.log('Invalid input:', error.field, error.message);
  } else {
    throw error;
  }
}

Error Properties

All errors extend OpenClawWalletError:

interface OpenClawWalletError extends Error {
  code: string;        // Machine-readable error code
  statusCode?: number; // HTTP status if applicable
  details?: unknown;   // Additional error details
}

Specific Error Types

// Configuration issues
class ConfigurationError extends OpenClawWalletError {
  code: 'CONFIGURATION_ERROR';
}
 
// Auth failures
class AuthenticationError extends OpenClawWalletError {
  code: 'UNAUTHORIZED' | 'INVALID_API_KEY';
}
 
// Rate limiting
class RateLimitError extends OpenClawWalletError {
  code: 'RATE_LIMITED';
  retryAfter: number; // Seconds until retry allowed
}
 
// Input validation
class ValidationError extends OpenClawWalletError {
  code: 'VALIDATION_ERROR';
  field: string;
}
 
// Network issues
class NetworkError extends OpenClawWalletError {
  code: 'NETWORK_ERROR' | 'TIMEOUT';
}
 
// Insufficient balance
class InsufficientFundsError extends OpenClawWalletError {
  code: 'INSUFFICIENT_FUNDS';
  required: string;
  available: string;
  token: string;
}
 
// Transaction failed
class TransactionError extends OpenClawWalletError {
  code: 'TRANSACTION_FAILED' | 'TRANSACTION_TIMEOUT';
  txHash?: string;
}
 
// Token launch errors
class TokenizeError extends OpenClawWalletError {
  code: 'ALREADY_LAUNCHED' | 'SYMBOL_TAKEN' | 'INVALID_IMAGE';
}

Error Code Reference

Error Code	HTTP Status	Error Class	Description
`CONFIGURATION_ERROR`	-	`ConfigurationError`	SDK misconfigured (missing API key, invalid options)
`UNAUTHORIZED`	401	`AuthenticationError`	Missing or invalid API key
`INVALID_API_KEY`	401	`AuthenticationError`	API key format is invalid
`RATE_LIMITED`	429	`RateLimitError`	Too many requests, retry after `retryAfter` seconds
`VALIDATION_ERROR`	400	`ValidationError`	Invalid input parameters
`NETWORK_ERROR`	-	`NetworkError`	Connection failed or request timed out
`TIMEOUT`	-	`NetworkError`	Request exceeded timeout limit
`INSUFFICIENT_FUNDS`	400	`InsufficientFundsError`	Not enough balance for operation
`TRANSACTION_FAILED`	500	`TransactionError`	On-chain transaction failed
`TRANSACTION_TIMEOUT`	500	`TransactionError`	Transaction confirmation timed out
`ALREADY_LAUNCHED`	400	`TokenizeError`	Account already launched a token
`SYMBOL_TAKEN`	400	`TokenizeError`	Token symbol already exists
`INVALID_IMAGE`	400	`TokenizeError`	Image URL invalid or inaccessible
`WALLET_NOT_FOUND`	404	`OpenClawWalletError`	No wallet exists for this account
`TOKEN_NOT_FOUND`	404	`OpenClawWalletError`	Token address or symbol not found
`SLIPPAGE_EXCEEDED`	400	`OpenClawWalletError`	Price moved beyond slippage tolerance

Retry Logic

The SDK has built-in retry for transient failures:

const wallet = new OpenClawWallet({
  apiKey: 'agent_xxx',
  maxRetries: 3,     // Retry up to 3 times
  retryDelay: 1000,  // Start with 1s delay
});

Custom Retry

async function swapWithRetry(params: SwapParams, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await wallet.trading.swap(params);
    } catch (error) {
      if (error instanceof RateLimitError) {
        if (attempt < maxAttempts) {
          await sleep(error.retryAfter * 1000);
          continue;
        }
      }
      throw error;
    }
  }
}

Retry Strategy by Error Type

Error Type	Retry?	Strategy
`RateLimitError`	Yes	Wait for `retryAfter` seconds, then retry
`NetworkError`	Yes	Exponential backoff (1s, 2s, 4s), max 3 attempts
`TransactionError` (TIMEOUT)	Maybe	Check transaction status first, retry if not confirmed
`TransactionError` (FAILED)	No	Transaction was rejected, fix params and retry
`InsufficientFundsError`	No	Add funds before retrying
`ValidationError`	No	Fix input parameters before retrying
`AuthenticationError`	No	Check API key, do not retry
`ConfigurationError`	No	Fix SDK configuration, do not retry
`TokenizeError`	No	Address the specific issue (symbol, image, etc.)
`SLIPPAGE_EXCEEDED`	Yes	Increase slippage or retry with fresh quote

Pro Tip: For SLIPPAGE_EXCEEDED errors, fetch a fresh quote with quoteOnly: true before retrying. Market conditions may have changed significantly.

WebSocket Errors

const dexWs = wallet.createDexWebSocket();
 
dexWs.on('error', (error) => {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof NetworkError) {
    console.log('Connection lost');
  }
});

Logging

Enable debug logging:

import { setLogLevel } from '@loomlay/openclaw-wallet-sdk';
 
setLogLevel('debug'); // 'debug' | 'info' | 'warn' | 'error' | 'none'