WDK logoWDK documentation
StartWalletsDeFi & FiatAI & CLITools

Handle Errors

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

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
import { DisposalError, MaximumFeeExceededError, ProviderRequiredError } from '@tetherto/wdk-wallet-tron'

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 instanceof MaximumFeeExceededError) {
    console.error('The transaction fee exceeds transactionMaxFee')
  } else if (error instanceof ProviderRequiredError) {
    console.error('Configure a TRON RPC provider')
  } else if (error instanceof DisposalError) {
    console.error('The account or signer has been disposed')
  } 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 has a missing or different owner')
  } 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
import { MaximumFeeExceededError, TransferError, TransferErrorReason } from '@tetherto/wdk-wallet-tron'

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 instanceof TransferError && error.reason === TransferErrorReason.INSUFFICIENT_TOKEN_BALANCE) {
    console.log('The wallet holds less than the requested token amount')
  } else if (error instanceof MaximumFeeExceededError) {
    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. The first contract must include an owner_address matching the wallet account; a missing or different owner is rejected before signing. 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() in a cleanup handler. The manager disposes its seed-created default signer and cached accounts that expose their private key. Dispose retained accounts without an exposed key explicitly, and dispose caller-owned signers after their final use.

Memory Cleanup
account.dispose()

wallet.dispose()

On this page