Proper error handling is essential when building hybrid dApps with the TAC SDK. This guide covers common errors you might encounter and strategies for handling them effectively.

​
Types of Errors

When working with the TAC SDK, you may encounter several types of errors:

  • Initialization Errors: Occur when setting up the SDK
  • Wallet Integration Errors: Related to TON wallet connections
  • Transaction Errors: Happen during transaction creation and sending
  • Validation Errors: Occur when validating addresses or parameters
  • Cross-Chain Errors: Arise during the cross-chain messaging process
  • Network Errors: Connection or timeout issues with TON or TAC networks

​
Handling SDK Initialization Errors

Errors that can occur during SDK initialization:

import { TacSdk, Network } from '@tonappchain/sdk';

async function initializeSdkWithErrorHandling() {
  try {
    const tacSdk = await TacSdk.create({
      network: Network.TESTNET
    });
    
    return tacSdk;
  } catch (error) {
    if (error.name === 'SettingError') {
      console.error('Settings contract error:', error.message);
      // Handle settings contract issues
    } else {
      console.error('SDK initialization failed:', error);
      // Handle other initialization errors
    }
    
    // Provide user feedback
    throw new Error('Failed to initialize TAC SDK. Please try again later.');
  }
}

​
Handling Wallet Integration Errors

Errors related to wallet connections:

import { SenderFactory } from '@tonappchain/sdk';

async function connectWalletWithErrorHandling() {
  try {
    const sender = await SenderFactory.getSender({
      tonConnect: tonConnectUI
    });
    
    return sender;
  } catch (error) {
    if (error.name === 'WalletError') {
      console.error('Wallet error:', error.message);
      // Handle wallet-specific errors
    } else if (error.code === 3) {
      console.error('User rejected the connection');
      // Handle user rejection
    } else {
      console.error('Wallet connection failed:', error);
      // Handle other wallet errors
    }
    
    // Provide appropriate feedback
    throw new Error('Failed to connect to wallet. Please try again.');
  }
}

​
Handling Transaction Errors

Errors during transaction creation and sending:

async function sendTransactionWithErrorHandling() {
  try {
    const transactionLinker = await tacSdk.sendCrossChainTransaction(
      evmProxyMsg,
      sender,
      assets
    );
    
    return transactionLinker;
  } catch (error) {
    if (error.name === 'ContractError') {
      console.error('Contract error:', error.message);
      // Handle contract not deployed on TVM side
    } else if (error.name === 'AddressError') {
      console.error('Address error:', error.message);
      // Handle invalid token address
    } else if (error.name === 'InsufficientFundsError') {
      console.error('Insufficient funds:', error.message);
      // Handle insufficient funds errors
    } else if (error.code === 3) {
      console.error('User rejected the transaction');
      // Handle user rejection
    } else {
      console.error('Transaction error:', error);
      // Handle other transaction errors
    }
    
    // Provide user-friendly error message
    throw new Error('Failed to send transaction. Please check your balance and try again.');
  }
}

​
Handling Validation Errors

Errors during parameter validation:

function validateParams() {
  try {
    // Validate token addresses
    if (!isValidTonAddress(tokenAddress)) {
      throw new Error('Invalid TON token address');
    }
    
    // Validate amounts
    if (amount <= 0) {
      throw new Error('Amount must be greater than zero');
    }
    
    // Validate EVM target address
    if (!isValidEvmAddress(evmTargetAddress)) {
      throw new Error('Invalid EVM target address');
    }
    
    return true;
  } catch (error) {
    console.error('Validation error:', error.message);
    // Handle validation errors with specific feedback
    throw error;
  }
}

// Helper functions
function isValidTonAddress(address) {
  return address && address.startsWith('EQ') && address.length === 48;
}

function isValidEvmAddress(address) {
  return /^0x[a-fA-F0-9]{40}$/.test(address);
}

​
Handling Transaction Tracking Errors

Errors during transaction status tracking:

import { OperationTracker, Network } from '@tonappchain/sdk';

async function trackTransactionWithErrorHandling(transactionLinker) {
  const tracker = new OperationTracker(Network.TESTNET);
  
  try {
    // Get operation ID with retries
    let operationId = null;
    let retries = 0;
    
    while (!operationId && retries < 10) {
      try {
        operationId = await tracker.getOperationId(transactionLinker);
        if (operationId) break;
      } catch (error) {
        console.warn(`Retry ${retries}: Failed to get operation ID`, error);
      }
      
      retries++;
      await new Promise(resolve => setTimeout(resolve, 3000)); // Wait 3 seconds between retries
    }
    
    if (!operationId) {
      throw new Error('Failed to get operation ID after maximum retries');
    }
    
    // Get operation status
    const status = await tracker.getOperationStatus(operationId);
    return status;
  } catch (error) {
    if (error.name === 'FetchError') {
      console.error('Failed to fetch from sequencer API:', error.message);
      // Handle API fetch errors
    } else {
      console.error('Tracking error:', error);
      // Handle other tracking errors
    }
    
    throw new Error('Failed to track transaction status. Please check again later.');
  }
}

​
Implementing a Retry Mechanism

For transient errors, implementing a retry mechanism can improve reliability:

async function withRetry(operation, maxRetries = 3, delay = 2000) {
  let lastError;
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      console.warn(`Attempt ${attempt} failed:`, error);
      lastError = error;
      
      // Don't retry if it's a validation error or user rejection
      if (error.name === 'ValidationError' || error.code === 3) {
        throw error;
      }
      
      // Wait before retrying
      await new Promise(resolve => setTimeout(resolve, delay * attempt));
    }
  }
  
  throw new Error(`Operation failed after ${maxRetries} attempts: ${lastError.message}`);
}

// Usage example
const result = await withRetry(() => tacSdk.sendCrossChainTransaction(evmProxyMsg, sender, assets));

​
Handling Failed Cross-Chain Transactions

If a transaction fails during cross-chain execution, you need to detect this and inform the user:

async function monitorTransactionForFailure(transactionLinker) {
  const tracker = new OperationTracker(Network.TESTNET);
  
  try {
    // Get simplified status with retry mechanism
    const status = await withRetry(
      () => tracker.getSimplifiedOperationStatus(transactionLinker)
    );
    
    if (status === 'FAILED') {
      // Get detailed status information
      const operationId = await tracker.getOperationId(transactionLinker);
      const detailedStatus = await tracker.getOperationStatus(operationId);
      
      console.error('Transaction failed at stage:', detailedStatus.stage);
      
      if (detailedStatus.note) {
        console.error('Failure details:', detailedStatus.note);
      }
      
      // Extract relevant error information for the user
      let userMessage = 'Transaction failed during processing.';
      
      if (detailedStatus.note && detailedStatus.note.errorName) {
        switch (detailedStatus.note.errorName) {
          case 'InvalidSlippage':
            userMessage = 'Transaction failed due to price movement. Try increasing slippage tolerance.';
            break;
          case 'InsufficientLiquidity':
            userMessage = 'Insufficient liquidity for this trade.';
            break;
          default:
            userMessage = `Transaction failed: ${detailedStatus.note.errorName}`;
        }
      }
      
      return {
        success: false,
        message: userMessage,
        details: detailedStatus
      };
    } else if (status === 'SUCCESSFUL') {
      return {
        success: true,
        message: 'Transaction completed successfully'
      };
    } else {
      return {
        success: false,
        pending: true,
        message: 'Transaction is still pending or status is unavailable'
      };
    }
  } catch (error) {
    console.error('Monitoring error:', error);
    
    return {
      success: false,
      message: 'Failed to monitor transaction status',
      error
    };
  }
}

​
Creating a Complete Error Handling System

Combining all these approaches, here’s a more comprehensive error handling system:

// Error types
class TacError extends Error {
  constructor(message, options = {}) {
    super(message);
    this.name = 'TacError';
    Object.assign(this, options);
  }
}

class ValidationError extends TacError {
  constructor(message, field) {
    super(message, { field });
    this.name = 'ValidationError';
  }
}

class NetworkError extends TacError {
  constructor(message, retryable = true) {
    super(message, { retryable });
    this.name = 'NetworkError';
  }
}

class UserRejectionError extends TacError {
  constructor() {
    super('User rejected the request');
    this.name = 'UserRejectionError';
  }
}

// Error handler class
class TacErrorHandler {
  static async withRetry(operation, maxRetries = 3, delay = 2000) {
    let lastError;
    
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        return await operation();
      } catch (error) {
        console.warn(`Attempt ${attempt} failed:`, error);
        lastError = error;
        
        // Don't retry certain errors
        if (
          error instanceof ValidationError || 
          error instanceof UserRejectionError ||
          (error instanceof NetworkError && !error.retryable)
        ) {
          throw error;
        }
        
        // Wait before retrying
        if (attempt < maxRetries) {
          await new Promise(resolve => setTimeout(resolve, delay * attempt));
        }
      }
    }
    
    throw lastError;
  }
  
  static handleSdkError(error) {
    if (error.code === 3) {
      return new UserRejectionError();
    }
    
    switch (error.name) {
      case 'SettingError':
        return new TacError('SDK configuration error', { original: error });
      case 'WalletError':
        return new TacError('Wallet connection error', { original: error });
      case 'ContractError':
        return new TacError('Smart contract error', { original: error });
      case 'AddressError':
        return new ValidationError('Invalid address', 'address');
      case 'FetchError':
        return new NetworkError('Network connection error', true);
      default:
        return new TacError('An unexpected error occurred', { original: error });
    }
  }
  
  static getUserFriendlyMessage(error) {
    if (error instanceof ValidationError) {
      return `Please check the ${error.field || 'input'}: ${error.message}`;
    }
    
    if (error instanceof UserRejectionError) {
      return 'Operation cancelled by user';
    }
    
    if (error instanceof NetworkError) {
      return error.retryable 
        ? 'Network error. Please try again later.'
        : 'Network error. Please check your connection.';
    }
    
    if (error instanceof TacError) {
      return error.message;
    }
    
    return 'An unexpected error occurred. Please try again later.';
  }
}

// Usage
async function safeOperation() {
  try {
    const result = await TacErrorHandler.withRetry(async () => {
      const tacSdk = await TacSdk.create({ network: Network.TESTNET });
      const transactionLinker = await tacSdk.sendCrossChainTransaction(evmProxyMsg, sender, assets);
      return transactionLinker;
    });
    
    return result;
  } catch (error) {
    const handledError = TacErrorHandler.handleSdkError(error);
    const userMessage = TacErrorHandler.getUserFriendlyMessage(handledError);
    
    // Display to user
    showErrorToUser(userMessage);
    
    // Log for debugging
    console.error('Operation failed:', handledError);
    
    throw handledError;
  }
}

Was this page helpful?