> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Playbooks

> How to handle every error code and failure scenario

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

```javascript theme={"system"}
// 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

```javascript theme={"system"}
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**:

```javascript theme={"system"}
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..." |

```javascript theme={"system"}
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**:

```javascript theme={"system"}
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]." |

```javascript theme={"system"}
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?" |

```javascript theme={"system"}
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'
  };
}
```

<Note>
  In status responses, slippage issues appear as substatus `SLIPPAGE_EXCEEDED`.
</Note>

***

### `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." |

```javascript theme={"system"}
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..." |

```javascript theme={"system"}
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." |

```javascript theme={"system"}
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

```javascript theme={"system"}
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       |

***

## Related Pages

* [Decision Tables](/agents/quick-start/decision-tables) - Error recovery decisions
* [Status & Recovery](/agents/workflows/status-recovery) - Handle transfer failures
* [Rate Limits](/api-reference/rate-limits) - Rate limit details