Error Playbooks

This page provides actionable playbooks for handling errors from the LI.FI API. For each error, you’ll find the cause, whether to retry, what to change, and how to communicate with users.

HTTP Status Codes

400 Bad Request

Cause: Invalid parameters in the request.

Retry?	No
Fix	Check and correct request parameters
User Message	”Invalid request. Please check your input and try again.”

Common Causes:

Missing required parameters
Invalid token address format
Invalid chain ID
Amount is 0 or negative
fromAddress not a valid address

// Example handling
if (error.status === 400) {
  console.error('Bad request:', error.message);
  // Parse error message for specific field
  // Don't retry - fix parameters
}

404 Not Found

Cause: No route available for the requested transfer.

Retry?	Maybe - with different parameters
Fix	Try different token pair, smaller amount, or different chains
User Message	”No route found for this transfer. Try a different token or amount.”

Common Causes:

Token pair not supported
Amount too small (below minimum)
Amount too large (exceeds liquidity)
Bridge temporarily unavailable

if (error.status === 404 || error.message.includes('No route')) {
  // Suggest alternatives
  const suggestions = [
    'Try a smaller amount',
    'Try a different destination token',
    'Use USDC or ETH as intermediate'
  ];
}

429 Too Many Requests

Cause: Rate limit exceeded.

Retry?	Yes - with backoff
Fix	Wait and retry with exponential backoff
User Message	”Too many requests. Please wait a moment.”

Backoff Strategy:

async function handleRateLimit(attempt) {
  const waitTime = Math.min(Math.pow(2, attempt) * 1000, 30000);
  console.log(`Rate limited. Waiting ${waitTime}ms...`);
  await sleep(waitTime);
}

// Usage in retry loop
for (let attempt = 0; attempt < 5; attempt++) {
  try {
    return await fetchQuote(params);
  } catch (error) {
    if (error.status === 429) {
      await handleRateLimit(attempt);
      continue;
    }
    throw error;
  }
}

Prevention:

Use an API key for higher limits
Cache chain and token data
Batch requests where possible

500 Internal Server Error

Cause: Server-side issue.

Retry?	Yes - once or twice
Fix	Wait briefly and retry
User Message	”Service temporarily unavailable. Retrying…“

if (error.status >= 500) {
  await sleep(2000);
  // Retry once
  return await fetchQuote(params);
}

503 Service Unavailable

Cause: Service temporarily down or overloaded.

Retry?	Yes - with longer delay
Fix	Wait 5-10 seconds and retry
User Message	”Service is temporarily unavailable. Please try again shortly.”

API Error Codes

The API returns error codes in the response body. Handle these specific scenarios:

`NO_POSSIBLE_ROUTE`

Cause: No bridge or DEX can fulfill the request.

Retry?	No - change parameters
Fix	Try different tokens, chains, or amount
User Message	”This transfer route is not available. Try a different token pair.”

Suggestions:

if (error.code === 'NO_POSSIBLE_ROUTE') {
  return {
    error: 'No route available',
    suggestions: [
      'Try USDC or USDT as the destination token',
      'Try a smaller amount',
      'Check if both chains support the tokens'
    ]
  };
}

`AMOUNT_TOO_LOW`

Cause: Transfer amount is below minimum threshold.

Retry?	No - increase amount
Fix	Increase `fromAmount`
User Message	”Amount too low for this transfer. Minimum is [X].”

if (error.code === 'AMOUNT_TOO_LOW') {
  // Error often includes minimum amount
  const minAmount = error.minAmount || 'unknown';
  return {
    error: `Minimum amount required: ${minAmount}`,
    action: 'Increase transfer amount'
  };
}

`AMOUNT_TOO_HIGH`

Cause: Amount exceeds available liquidity.

Retry?	No - decrease amount
Fix	Decrease `fromAmount` or split into multiple transfers
User Message	”Amount exceeds available liquidity. Try a smaller amount.”

`INSUFFICIENT_LIQUIDITY`

Cause: Not enough liquidity in pools.

Retry?	Maybe - try later
Fix	Try smaller amount, different bridge, or wait
User Message	”Insufficient liquidity for this transfer. Try a smaller amount.”

Slippage Error (code 1007)

Cause: Price impact exceeds slippage tolerance.

Retry?	Yes - with adjusted slippage
Fix	Increase `slippage` parameter or decrease amount
User Message	”Price moved too much. Would you like to accept higher slippage?”

if (error.code === 1007 || error.message?.includes('slippage')) {
  // Offer to increase slippage
  const currentSlippage = params.slippage || 0.005;
  const suggestedSlippage = Math.min(currentSlippage * 2, 0.03);
  
  return {
    error: 'Slippage exceeded',
    currentSlippage: `${currentSlippage * 100}%`,
    suggestedSlippage: `${suggestedSlippage * 100}%`,
    action: 'Retry with higher slippage or smaller amount'
  };
}

In status responses, slippage issues appear as substatus SLIPPAGE_EXCEEDED.

`TOOL_TIMEOUT`

Cause: Bridge or DEX response timeout.

Retry?	Yes - immediately
Fix	Retry the request
User Message	”Request timed out. Retrying…”

`CHAIN_NOT_SUPPORTED`

Cause: Requested chain is not available.

Retry?	No
Fix	Use a supported chain
User Message	”This blockchain is not currently supported.”

if (error.code === 'CHAIN_NOT_SUPPORTED') {
  // Fetch supported chains
  const chains = await getChains();
  return {
    error: 'Chain not supported',
    supportedChains: chains.map(c => ({ id: c.id, name: c.name }))
  };
}

`TOKEN_NOT_SUPPORTED`

Cause: Token is not available for transfers.

Retry?	No
Fix	Use a different token
User Message	”This token is not supported for transfers.”

Transaction Errors

Errors that occur during transaction execution (not API errors):

`execution reverted`

Cause: Smart contract rejected the transaction.

Retry?	Maybe - get new quote
Fix	Quote may be stale; get fresh quote and retry
User Message	”Transaction failed. Getting a fresh quote…”

if (error.message.includes('reverted')) {
  // Quote expired or conditions changed
  console.log('Transaction reverted. Fetching new quote...');
  const newQuote = await getQuote(originalParams);
  // Retry with new quote
}

`insufficient funds`

Cause: Wallet doesn’t have enough balance.

Retry?	No
Fix	User needs to add funds
User Message	”Insufficient balance. You need [X] [TOKEN] plus gas.”

if (error.message.includes('insufficient funds')) {
  return {
    error: 'Insufficient balance',
    required: {
      token: quote.action.fromAmount,
      gas: 'Plus gas fees in native token'
    }
  };
}

`user rejected`

Cause: User declined the transaction in their wallet.

Retry?	No - ask user again
Fix	Ask if user wants to try again
User Message	”Transaction cancelled. Would you like to try again?”

`nonce too low`

Cause: Pending transaction with same nonce.

Retry?	Wait for pending tx
Fix	Wait for pending transaction or speed it up
User Message	”You have a pending transaction. Please wait or speed it up.”

Error Handling Template

async function handleLiFiError(error, params) {
  const code = error.code || error.status;
  
  // Rate limiting
  if (code === 429) {
    return { retry: true, wait: true, message: 'Rate limited' };
  }
  
  // Server errors
  if (code >= 500) {
    return { retry: true, message: 'Server error' };
  }
  
  // No route
  if (code === 404 || error.code === 'NO_POSSIBLE_ROUTE') {
    return {
      retry: false,
      message: 'No route found',
      suggestions: getRouteSuggestions(params)
    };
  }
  
  // Amount issues
  if (error.code === 'AMOUNT_TOO_LOW') {
    return {
      retry: false,
      message: `Amount too low. Minimum: ${error.minAmount}`,
      action: 'increase_amount'
    };
  }
  
  // Slippage
  if (error.code === 1007 || error.message?.includes('slippage')) {
    return {
      retry: true,
      adjustParam: { slippage: params.slippage * 2 },
      message: 'Consider increasing slippage'
    };
  }
  
  // Default
  return {
    retry: false,
    message: error.message || 'Unknown error'
  };
}

function getRouteSuggestions(params) {
  return [
    'Try USDC, USDT, or ETH instead',
    'Try a smaller amount',
    'Check if tokens are supported on both chains'
  ];
}

Quick Reference

Error	Retry?	Action
400 Bad Request	No	Fix parameters
404 No Route	Maybe	Change tokens/amount
429 Rate Limited	Yes	Exponential backoff
500 Server Error	Yes	Wait and retry
AMOUNT_TOO_LOW	No	Increase amount
Slippage error (1007)	Maybe	Increase slippage
execution reverted	Maybe	Get new quote
insufficient funds	No	User needs funds
user rejected	No	Ask user again

Decision Tables - Error recovery decisions
Status & Recovery - Handle transfer failures
Rate Limits - Rate limit details

​HTTP Status Codes

​400 Bad Request

​404 Not Found

​429 Too Many Requests

​500 Internal Server Error

​503 Service Unavailable

​API Error Codes

​NO_POSSIBLE_ROUTE

​AMOUNT_TOO_LOW

​AMOUNT_TOO_HIGH

​INSUFFICIENT_LIQUIDITY

​Slippage Error (code 1007)

​TOOL_TIMEOUT

​CHAIN_NOT_SUPPORTED

​TOKEN_NOT_SUPPORTED

​Transaction Errors

​execution reverted

​insufficient funds

​user rejected

​nonce too low

​Error Handling Template

​Quick Reference

​Related Pages

HTTP Status Codes

400 Bad Request

404 Not Found

429 Too Many Requests

500 Internal Server Error

503 Service Unavailable

API Error Codes

`NO_POSSIBLE_ROUTE`

`AMOUNT_TOO_LOW`

`AMOUNT_TOO_HIGH`

`INSUFFICIENT_LIQUIDITY`

Slippage Error (code 1007)

`TOOL_TIMEOUT`

`CHAIN_NOT_SUPPORTED`

`TOKEN_NOT_SUPPORTED`

Transaction Errors

`execution reverted`

`insufficient funds`

`user rejected`

`nonce too low`

Error Handling Template

Quick Reference

Related Pages