Handle Errors

Handle errors, manage fees, and dispose of sensitive data in gasless TON wallets.

This guide covers how to handle gasless transfer errors and handle native TON transaction errors, plus best practices for fee management and memory cleanup.

Handle Gasless Transfer Errors

Gasless transfers can fail for reasons specific to the paymaster model. Wrap calls to account.transfer() in try/catch blocks:

Gasless Transfer Error Handling

try {
  const result = await account.transfer({
    token: 'EQ...',
    recipient: 'EQ...',
    amount: 1000000000
  })
  console.log('Transfer hash:', result.hash)
} catch (error) {
  if (error.message.includes('insufficient jetton balance')) {
    console.error('Please add more Jetton tokens to your wallet')
  } else if (error.message.includes('insufficient paymaster balance')) {
    console.error('Please add more paymaster tokens for gas fees')
  } else if (error.message.includes('invalid address')) {
    console.error('The recipient address is invalid')
  } else if (error.message.includes('max fee')) {
    console.error('The transfer fee exceeds your configured maximum')
  } else {
    console.error('Transfer failed:', error.message)
  }
}

Handle Native TON Transaction Errors

Native TON transactions sent via account.sendTransaction() can fail for standard reasons:

Transaction Error Handling

try {
  const result = await account.sendTransaction({
    to: 'EQ...',
    value: 1000000000
  })
  console.log('Transaction hash:', result.hash)
} catch (error) {
  if (error.message.includes('insufficient balance')) {
    console.error('Not enough TON to complete transaction')
  } else {
    console.error('Transaction failed:', error.message)
  }
}

Best Practices

Manage Fee Limits

Set transferMaxFee when creating the wallet to prevent gasless transfers from exceeding a maximum cost. You can retrieve current network rates using wallet.getFeeRates():

Fee Management

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

Dispose of Sensitive Data

Call dispose() on accounts and wallet managers to clear private keys and sensitive data from memory when they are no longer needed:

Memory Cleanup

account.dispose()

wallet.dispose()

Always call dispose() in a finally block or cleanup handler to ensure sensitive data is cleared even if an error occurs.