Handle Errors

This guide covers how to handle gas-free transfer errors, unsupported native transaction methods, and transaction lookup errors, plus best practices for fee management and memory cleanup.

Handle Gas-Free Transfer Errors

Gas-free transfers can fail for reasons including exceeded fee limits or insufficient token balances. Wrap calls to account.transfer() in try/catch blocks:

try {
  const result = await account.transfer({
    token: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT
    recipient: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
    amount: 1000000
  }, {
    transferMaxFee: 1000n
  })
  console.log('GasFree relay accepted:', result.hash)
  console.log('Fee paid:', result.fee, 'token units')
} catch (error) {
  console.error('Transfer failed:', error.message)
  if (error.message.includes('exceeds the transfer max fee')) {
    console.log('Transfer cancelled: fee too high')
  } else if (error.message.toLowerCase().includes('insufficient')) {
    console.log('Please add more TRC20 tokens to your wallet')
  }
}

The returned hash is a GasFree relay ID, not proof of an included TRON transaction. Pass it to waitForTransaction(); the module resolves the native hash through the relay and then reports TRON finality and execution success.

Handle Unsupported Native Transaction Methods

The Tron GasFree module does not support native TRX transaction execution, native fee quotes, or offline transaction signing. The related methods are present for wallet-interface compatibility and throw module-specific errors:

try {
  await account.sendTransaction({
    to: 'TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH',
    value: 1000000
  })
} catch (error) {
  if (error.message.includes("Method 'sendTransaction(tx)' not supported")) {
    console.error('Use the base Tron wallet module for native TRX transactions.')
  }
}

Handle Transaction Lookup Errors

getTransaction() and waitForTransaction() first resolve the GasFree transfer ID through the GasFree API, then query TRON. A successful GasFree response without an on-chain hash is treated as not found and can be retried by waitForTransaction(). An HTTP or API error from the GasFree provider is a provider failure and can reject immediately, so handle it separately from a normal relay delay.

Best Practices

Manage Fee Limits

Pass transferMaxFee in the second argument to each account.transfer() call that needs a cap. The constructor-level field is not used as a default by the current runtime. You can retrieve current network rates using wallet.getFeeRates():

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:

account.dispose()

wallet.dispose()