Handle Errors

This guide covers how to handle transaction errors and handle token transfer errors, plus best practices for fee management and derived key cleanup.

Handle Transaction Errors

Wrap transactions in try/catch blocks to handle common failure scenarios. Use account.sendTransaction() with proper error handling:

Transaction Error Handling

try {
  const result = await account.sendTransaction({
    to: 'EQ...',
    value: 1000000000,
    bounceable: true
  })
  console.log('Signed transfer body hash:', result.hash)
  console.log('Fee paid:', result.fee, 'nanotons')
} catch (error) {
  if (error.message.includes('insufficient balance')) {
    console.error('Not enough TON to complete transaction')
  } else if (error.message === 'Exceeded maximum fee cost for transaction operation.') {
    console.error('Transaction fee exceeds transactionMaxFee')
  } else if (error.message.includes('invalid address')) {
    console.error('Invalid recipient address')
  } else if (error.message.includes('timeout')) {
    console.error('Network timeout, please try again')
  } else {
    console.error('Transaction failed:', error.message)
  }
}

Handle Token Transfer Errors

Jetton transfers can fail for multiple reasons, such as insufficient token balances. Use account.transfer() with error handling:

Token Transfer Error Handling

try {
  const result = await account.transfer({
    token: 'EQ...',
    recipient: 'EQ...',
    amount: 1000000
  })
  console.log('Signed transfer body hash:', result.hash)
} catch (error) {
  console.error('Transfer failed:', error.message)
  if (error.message.toLowerCase().includes('insufficient')) {
    console.log('Please add more tokens to your wallet')
  } else if (error.message === 'Exceeded maximum fee cost for transfer operations.') {
    console.log('The transfer fee exceeds your configured maximum')
  }
}

Set transactionMaxFee when creating the wallet to cap native sendTransaction() and signTransaction() costs. Set transferMaxFee separately for Jetton transfer() costs. You can retrieve mainnet TON API rates using wallet.getFeeRates(). Through 1.0.0-beta.12, this method does not follow a configured testnet client and returns the same calculated value for normal and fast:

Fee Management

const feeRates = await wallet.getFeeRates()
console.log('Normal fee rate:', feeRates.normal, 'nanotons')
console.log('Fast fee rate:', feeRates.fast, 'nanotons')

Dispose Derived Account Keys

Call dispose() on accounts and wallet managers to clear cached accounts' derived private keys when they are no longer needed:

Memory Cleanup

account.dispose()

wallet.dispose()

Call dispose() in a finally block or cleanup handler so derived account keys are cleared even if an error occurs. In the current beta, wallet.dispose() does not zero or unset wallet.seed; manage the seed lifecycle separately and release all manager references when finished.

Handle Errors

Handle Transaction Errors

Handle Token Transfer Errors

Best Practices

Manage Fee Limits

Dispose Derived Account Keys

On this page