Error Handling

Error Callbacks

The simplest way to handle errors is through onSwapError:

const widget = new TokenFlightWidget({
  container: '#widget',
  config: {
    toToken: { chainId: 8453, address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' },
    tradeType: 'EXACT_OUTPUT',
    amount: '100',
    theme: 'dark',
  },
  callbacks: {
    onSwapError: (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.