Handle Errors

This guide covers how to handle transaction errors and handle token transfer errors, plus best practices for fee management and memory 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 tx = {
    to: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
    value: 1000000 // 1 TRX in sun
  }

  const result = await account.sendTransaction(tx)
  console.log('Transaction submitted:', result.hash)
  console.log('Fee paid:', result.fee, 'sun')
  console.log('Activation fee:', result.activationFee, 'sun')
} catch (error) {
  if (error.message.toLowerCase().includes('insufficient')) {
    console.error('Not enough TRX to complete transaction')
  } else if (error.message.includes('Exceeded maximum fee')) {
    console.error('The transaction fee exceeds transactionMaxFee')
  } else if (error.message === 'The transaction id does not match its raw data.') {
    console.error('The pre-built transaction failed its txID integrity check')
  } else if (error.message.toLowerCase().includes('transaction owner')) {
    console.error('The pre-built transaction is owned by a different account')
  } else {
    console.error('Transaction failed:', error.message)
  }
}

Handle Token Transfer Errors

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

Token Transfer Error Handling

try {
  const result = await account.transfer({
    token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT
    recipient: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
    amount: 1000000
  })
  console.log('Transfer submitted:', result.hash)
  console.log('Fee paid (sun):', result.fee)
} catch (error) {
  console.error('Transfer failed:', error.message)
  if (error.message.toLowerCase().includes('insufficient')) {
    console.log('Please add more TRC20 tokens to your wallet')
  } else if (error.message.toLowerCase().includes('max fee')) {
    console.log('The transfer fee exceeds your configured maximum')
  }
}

These calls can return after broadcast before solidification or contract execution is known. Use waitForTransaction() with the returned TRON hash and inspect both finality and success before treating the transfer as complete.

Best Practices

Manage Fee Limits

Set transactionMaxFee when creating the wallet to cap sendTransaction() and signTransaction() costs for native TRX transfers, smart-contract call descriptors, and pre-built TronWeb transactions. Set transferMaxFee separately for TRC20 transfer() costs. Native TRX quotes and results include activationFee when the recipient account must be activated.

For unsigned pre-built TronWeb transactions, WDK verifies that the txID matches the serialized raw data and that the owner address matches the wallet account before this wallet signs. Already-signed inputs use the direct-broadcast path and do not repeat these unsigned-input guards.

You can retrieve current network rates using wallet.getFeeRates():

Fee Management

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

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.