Error Handling

Should you read this?

Read this page when you need to show helpful messages for wallet failures, API failures, quote failures, or invalid config.

If you are debugging a live issue, start with Troubleshooting first.

Before you start

• Quote failures can appear as widget UI state before the user signs anything.
• Wallet rejections usually happen during awaiting-wallet.
• After a transaction is signed, use the order and transaction hash to investigate.

Error Callbacks

The simplest way to handle errors is through the callback for your flow. This example uses onDepositError because the config is EXACT_OUTPUT:

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  callbacks: {
    onDepositError: (error) => {
      switch (error.code) {
        case 'TF4003':
          showToast('Insufficient balance');
          break;
        case 'TF2003':
          showToast('Wallet action failed');
          break;
        default:
          showToast(error.message);
      }
    },
  },
});

TokenFlightError

try {
  widget.initialize();
} catch (err) {
  if (err instanceof TokenFlightError) {
    console.error(`[${err.code}] ${err.message}`);
    console.error('Details:', err.details);
  }
}

Common Error Codes

Code	Name	Description
TF1001	INVALID_CONFIG	Invalid configuration provided
TF1002	INVALID_TOKEN_IDENTIFIER	Bad token identifier format
TF1003	INVALID_AMOUNT	Invalid amount value
TF1004	MISSING_REQUIRED_CONFIG	Missing required configuration
TF2001	WALLET_NOT_CONNECTED	No wallet connected
TF2003	WALLET_ACTION_FAILED	Wallet action failed
TF2004	WALLET_ACTION_REJECTED	User rejected a wallet prompt
TF3001	API_REQUEST_FAILED	API request failed
TF3002	API_TIMEOUT	API request timed out
TF3004	QUOTE_FAILED	No route could be quoted
TF3005	QUOTE_EXPIRED	Quote expired and needs refresh
TF4001	TRANSACTION_FAILED	On-chain transaction reverted
TF4002	TRANSACTION_REJECTED	User rejected the transaction
TF4003	INSUFFICIENT_BALANCE	Not enough tokens for the route
TF5001	ELEMENT_NOT_FOUND	Container selector did not match the DOM
TF5002	INITIALIZATION_FAILED	Widget failed to mount

Scenario Notes

• Quote-unavailable states may surface as UI state without a dedicated callback.
• Wallet rejection commonly appears as TF2003 or TF2004, depending on the adapter.
• Cross-chain recipient validation can block execution before any transaction is sent.

Next step

• Need to understand where errors happen? Read Transaction Lifecycle.
• Need payment-safe handling? Read Backend Verification.