Error Handling

KyberSwap Error Handling Skill

This skill helps diagnose and resolve errors that occur when swapping tokens through the KyberSwap Aggregator API.

When to use

Use this skill when:

• A user encounters an error while using KyberSwap API to swap tokens
• A swap transaction fails on-chain
• The KyberSwap API returns an error code
• A user needs help understanding why their swap failed
• Troubleshooting integration issues with KyberSwap Aggregator

Error Categories

Errors are categorized into three phases:

1. API Errors - Returned by KyberSwap API during route fetching/building
2. Pre-Transaction Errors - Route built successfully, but failed to push the transaction on-chain
3. On-Chain Errors - Transaction reverts on the blockchain

Error Handling Workflow

Follow this systematic approach when debugging swap failures:

Step 1: Identify Error Phase

1. API Error? Check the HTTP response code and code field in JSON
2. Pre-tx Error? Check gas estimation or simulation results
3. On-chain Error? Check transaction receipt and revert reason

Step 2: Look Up Error in This Guide

1. Find the error code (e.g., 4008, 4222, 4227) in the API response
2. Navigate to the corresponding error section below:
   • API Errors Reference - for errors during route fetching/building
   • Pre-Transaction Errors - for gas estimation failures
   • On-Chain Errors - for transaction reverts
3. Read the Description, Common Causes, and Solutions for your specific error
4. Follow the recommended solutions in order

Common Quick Fixes

Best Practices

Route Freshness

• Never cache routes for more than 5-10 seconds
• Always re-fetch route immediately before building transaction
• Markets move fast - stale routes cause failures

Slippage Configuration

• Stablecoin ↔ Stablecoin (e.g. USDC→USDT): 5 bps (0.05%)
• Common tokens (e.g. ETH→USDC, WBTC→ETH): 50 bps (0.50%)
• All other / unknown pairs: 100 bps (1.00%)

Rate Limiting

• Always include X-Client-Id header

API Errors Reference

Note: Error codes 4008, 4009, 4010, 4011 are documented in official KyberSwap API docs. Other codes listed here (including 5-digit variants like 40010, 40011) are based on observed API behavior and may change without notice.

Maintenance note: Observed (non-official) error codes should be periodically re-verified against live API behavior to ensure they are still accurate and relevant.

Error 4000: Bad Request

{
  "code": 4000, 
  "message": "bad request", 
  "details": [
    {
      "fieldViolations": [
        {
          "field": $validField,
          "description": "invalid"
        }
      ]
    }
  ]
}

Description: Generic bad request error with field-specific validation failures.

Common Field Violations:

Solutions:

1. Read the fieldViolation and description in the API response to see which field failed and the root cause.
2. For address-related fields: use valid 42-character hex strings with lowercase 0x prefix (not 0X)
3. For amount-related fields: use valid integer strings in wei - no decimals, no scientific notation, no hex
4. For deadline: use a Unix timestamp in the future (past timestamps are invalid)
5. For slippageTolerance in build: keep under 2000, or set ignoreCappedSlippage: true
6. Check that all required parameters are included

Error 4001: Query Parameters Malformed

{
  "code": 4001,
  "message": "unable to bind query parameters",
  "details": null,
  "requestId": ""
}

Description: The API cannot parse the query parameters in the request.

Common Causes:

• Invalid value for a boolean query parameter (e.g. not accepted by the API)

Solutions:

1. For boolean query parameters: use exactly true or false as required by the API. Avoid other values (e.g. 1/0, "yes"/"no").

Error 4002: Request Body Malformed

{
  "code": 4002,
  "message": "unable to bind request body",
  "details": null,
  "requestId": ""
}

Description: The POST request body cannot be parsed (for /route/build endpoint).

Common Causes:

• Data types don't match schema (e.g., string instead of number)
• Invalid JSON syntax in request body

Solutions:

1. Ensure that deadline and slippageTolerance are Numbers. enableGasEstimation and ignoreCappedSlippage are booleans (true or false)
2. DO NOT modify the routeSummary object - pass it unchanged

Error 4003: Invalid Swap

{"code": 4003, "message": "invalid swap"}

Description: The get route request is invalid and cannot be processed.

Common Causes:

• Error in dex integration from KyberSwap

Solutions:

1. Try to re-fetch the route after a period of time (recommended)
2. Use excludedSources to skip the failing DEX
3. Report to KyberSwap

Error 4004: Invalid config for fee receiver

{
  "code": 4004,
  "message": "invalid value",
  "details": null,
  "requestId": ""
}

Description: The fee configuration is incomplete or invalid. When feeAmount is specified, a valid feeReceiver address must also be provided to receive the collected fees.

Common Causes:

• feeAmount is set but feeReceiver is missing or empty
• Mismatch between number of feeAmount values and feeReceiver addresses when using multiple fee receivers

Solutions:

1. Add a valid feeReceiver address - Provide the wallet address that should receive the fees
2. Match fee arrays - When using multiple receivers, ensure feeAmount and feeReceiver have the same number of comma-separated values
3. Remove fee parameters entirely - If you don't need to charge fees, omit both feeAmount and feeReceiver

Error 4005: Fee Amount Greater Than Amount In

{
  "code": 4005,
  "message": "feeAmount is greater than amountIn",
  "details": null,
  "requestId": ""
}

Description: The configured fee exceeds the input amount when charging by input token.

Common Causes:

• feeAmount set too high relative to amountIn
• Incorrect isInBps configuration (treating BPS as absolute value or vice versa)
• Multiple fee receivers with combined fees exceeding input

Solutions:

1. Reduce feeAmount to be less than amountIn
2. If using BPS (isInBps: true), verify calculation: 10 = 0.1%, 100 = 1%
3. When not using BPS, feeAmount is in token wei - ensure it's less than amountIn
4. For multiple fees, ensure sum of all feeAmount values < amountIn

Error 4007: Fee Amount Greater Than Amount Out

{
  "code": 4007,
  "message": "feeAmount is greater than amountOut",
  "details": null,
  "requestId": ""
}

Description: The configured fee exceeds the output amount when charging by output token.

Common Causes:

• feeAmount set too high relative to expected amountOut
• Incorrect isInBps configuration (treating BPS as absolute value or vice versa)
• Multiple fee receivers with combined fees exceeding input
• Using chargeFeeBy: "currency_out" with miscalculated fee

Solutions:

1. Reduce feeAmount to be less than expected amountOut
2. If using BPS (isInBps: true), verify calculation: 10 = 0.1%, 100 = 1%
3. When not using BPS, feeAmount is in token wei - ensure it's less than amountOut
4. Consider switching to chargeFeeBy: "currency_in" for predictable fee calculation
5. Calculate maximum allowable fee based on estimated output

Error 4008: Route Not Found

{"code": 4008, "message": "route not found"}

Description: No viable swap path exists between the specified tokens.

Common Causes:

• No liquidity pools exist for the token pair
• Token is not listed on any DEX on this chain
• Extremely low liquidity for the pair
• Token has transfer restrictions blocking swaps
• Too restrictive source filtering (includedSources/excludedSources)

Solutions:

1. Verify both tokens are valid and tradeable on this chain
2. Remove source filters to search all liquidity sources
3. Try a different chain if the token is multi-chain
4. Reduce trade size - some routes only work for smaller amounts
5. Refetch route and retry after a short period of time

Error 4009: Amount In Exceeds Maximum

{"code": 4009, "message": "amountIn is greater than max allowed"}

Description: The input amount exceeds the maximum supported by the available liquidity sources or by the current KyberSwap API configuration.

Common Causes:

• Trade size too large

Solutions:

1. Reduce the trade size - split into multiple smaller swaps

Error 4010: No Eligible Pools

{"code": 4010, "message": "route not found"}

Description: No pools are eligible for routing after applying filters.

Common Causes:

• All pools filtered out by includedSources/excludedSources
• Liquidity exists but doesn't meet minimum requirements
• Pools exist but have insufficient liquidity for the amount

Solutions:

1. Remove or adjust source filters
2. Reduce trade size to fit available liquidity
3. Try without onlyDirectPools or onlySinglePath restrictions
4. Check if pools exist on block explorer for the token pair

Error 4011: Token Not Found

{"code": 4011, "message": "token not found"}

Description: The specified token address cannot be found or is not supported.

Common Causes:

• Token address is incorrect or has typo
• Token doesn't exist on this chain
• Token is not indexed by KyberSwap
• Using wrong chain for the token
• Token was recently deployed and not yet indexed

Solutions:

1. Verify the token contract address on a block explorer
2. Ensure you're using the correct chain
3. Check token address checksums (case-sensitive for EIP-55)
4. For native tokens, use: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
5. For newly deployed tokens, wait for indexing
6. Try swapping a different, well-known token to verify API connectivity

Error 4222: Quoted Amount Smaller Than Estimated

Last verified: 2026-02-19 (observed behavior, not officially documented)

{
  "code": 4222,
  "message": "quoted amount is smaller than estimated",
  "details": null,
  "requestId": ""
}

Description: The actual quote from an RFQ market maker or limit order source is lower than the initially estimated output amount, causing the route to be rejected.

Common Causes:

• Market price moved between estimation and quote request
• RFQ market maker cannot offer the estimated rate for your trade size
• Stale estimation due to AMM pool state changes
• Price impact compounding in multi-hop routes
• High volatility in the token pair

Solutions:

1. Fetch new route and retry the request - Stale routes can cause failures (recommended)
2. Use excludeRFQSources: true - Avoid RFQ sources and rely only on AMM pools for more consistent pricing
3. Use onlyScalableSources: true - Stick to pools with predictable, calculable pricing
4. Reduce trade size - Smaller amounts typically get better and more stable quotes
5. Increase slippage tolerance - If using a tight slippageTolerance, the quote may fall outside the acceptable range

Error 4227: Gas Estimation Failed

Last verified: 2026-02-19 (observed behavior, not officially documented)

{
  "code": 4227,
  "message": "estimate gas failed: return amount is not enough",
  "details": ["estimate gas failed: return amount is not enough"],
  "requestId": "",
  "suggestedSlippage": 230
}

{
  "code": 4227,
  "message": "estimate gas failed: insufficient funds for gas * price + value: have 1031632630608236 want 2000000000000000",
  "details": [
    "estimate gas failed: insufficient funds for gas * price + value: have 1031632630608236 want 2000000000000000"
  ],
  "requestId": ""
}

{
  "code": 4227,
  "message": "estimate gas failed: execution reverted: TransferHelper: TRANSFER_FROM_FAILED",
  "details": [
    "estimate gas failed: execution reverted: TransferHelper: TRANSFER_FROM_FAILED"
  ],
  "requestId": ""
}

Description: Gas estimation failed during the build step. The API simulates the transaction before returning it, and the simulation reverted. The message field contains the specific revert reason. This error has several variants depending on the root cause.

Variant 1: "return amount is not enough"

The simulated swap would return less than the minimum acceptable amount based on current slippage settings. The API provides a suggestedSlippage value (in bps) that would make the transaction succeed.

Common Causes:

• Price moved unfavorably between route fetch and build
• Slippage tolerance is too tight for current market conditions
• High volatility in the token pair
• Route includes RFQ sources with changing quotes

Solutions:

1. Fetch a new route and retry - The route is stale; get a fresh quote (recommended)
2. Use the suggestedSlippage value - The API returns a suggested slippage (e.g., 230 = 2.3%) that would work
3. Increase slippage tolerance - Use a higher slippageTolerance in the build request

Note: The suggestedSlippage field is helpful but refetching a fresh route is generally the better approach as it gives you an updated price quote.

Variant 2: "insufficient funds for gas * price + value"

The sender's native token balance (e.g., ETH, MATIC) is not enough to cover the transaction value plus gas fees.

Common Causes:

• Sender wallet does not have enough native token to cover amountIn (for native token swaps) plus gas fees
• Gas price spiked between route fetch and build, increasing the total cost
• The sender address provided in the build request holds less native token than expected

Solutions:

1. Check sender's native token balance - Ensure the sender address has enough native token to cover the full transaction value plus gas fees
2. Reduce the swap amount - Lower amountIn to leave room for gas fees
3. Top up the wallet - Transfer more native token to the sender address before retrying

Variant 3: "TransferHelper: TRANSFER_FROM_FAILED"

The router contract failed to pull the input token from the sender during simulation.

Common Causes:

• Sender has not approved the router contract to spend the input token
• Token approval amount is less than amountIn
• Sender's token balance is less than amountIn
• The token contract has transfer restrictions (e.g., blacklists, paused transfers, max transfer limits)

Solutions:

1. Check token approval - Ensure the sender has approved the routerAddress to spend at least amountIn of the input token
2. Check token balance - Ensure the sender holds at least amountIn of the input token
3. Check token restrictions - Some tokens have blacklists, transfer fees, or pause mechanisms that block transfers

Error 40010: Empty sender address

Last verified: 2026-02-19 (observed behavior, not officially documented)

{
  "code": 40010,
  "message": "sender address can not be empty when enable gas estimation",
  "details": null,
  "requestId": ""
}

Description: The API requires a sender address to estimate gas costs, but none was provided in the request.

Common Causes:

• Missing sender parameter in the API request
• Empty string passed as sender address
• Using enableGasEstimation: true without providing a sender

Solutions:

1. Provide a valid sender address - Include the sender parameter with the user's wallet address
2. Disable gas estimation - If you don't need gas costs, set enableGasEstimation: false (or omit it)
3. Use a placeholder address - For quote-only requests, you can use any valid address format (e.g., 0x0000000000000000000000000000000000000001)

Error 40011: Filtered Liquidity Sources

Last verified: 2026-02-19 (observed behavior, not officially documented)

{"code": 40011, "message": "filtered liquidity sources"}

Description: A route exists but was filtered out by user-defined liquidity source restrictions, or the user attempted to include a non-existent liquidity source in the includedSources field.

Common Causes:

• Using includedSources that do not exist or have no liquidity for this pair

• Using excludedSources that filters out all viable routes

Solutions:

1. Remove includedSources and excludedSources parameters
2. Expand the list of included sources
3. Check which DEXs have liquidity for this pair and include them

Error 4221: WETH Not Configured

{"code": 4221, "message": "weth not found"}

Description: WETH (Wrapped ETH) is not configured for this network.

Common Causes:

• Chain doesn't support native token wrapping
• Network misconfiguration
• Using unsupported testnet

Solutions:

1. Use the wrapped native token address directly instead of native token address
2. Check if WETH is configured on this chain

Error 4990: Request Canceled

Last verified: 2026-02-19 (observed behavior, not officially documented)

{"code": 4990, "message": "request was canceled"}

Description: The request was canceled.

Common Causes:

• Client canceled the request
• Network latency causing timeout

Solutions:

1. Retry the request
2. Check network connectivity
3. Try during lower traffic periods
4. If persistent, contact KyberSwap support with requestId

Error 500: Internal Server Error

{
  "code": 500,
  "message": "internal server error",
  "details": null,
  "requestId": ""
}

Description: An unexpected error occurred on the KyberSwap server. This is typically a bug or edge case that the API didn't handle gracefully.

Common Causes:

• Invalid feeReceiver address format (e.g., non-hex string like "invalid")
• Server-side processing error
• Malformed data that bypassed initial validation

Solutions:

1. Verify all addresses - Ensure all address fields are valid 42-character hex strings starting with 0x
2. Don't modify routeSummary - Pass the routeSummary exactly as returned from get route API
3. Retry the request - The error may be transient

HTTP 404: Chain Not Found

{
  "message": "",
  "path": "/invalidchain/api/v1/routes?...",
  "request_id": "",
  "request_ip": "",
  "status": 404
}

Description: The specified chain in the API path is not supported or doesn't exist.

Common Causes:

• Typo in chain name (e.g., "etherium" instead of "ethereum")
• Using a testnet that's not supported (e.g., "goerli", "sepolia")
• Chain name is case-sensitive or formatted incorrectly

Solutions:

1. Use correct chain names - Refer to the supported chains list: ethereum, bsc, polygon, arbitrum, optimism, avalanche, base, linea, mantle, sonic, berachain, ronin, unichain, hyperevm, plasma, etherlink, monad, megaeth
2. Check spelling - Chain names are lowercase and must match exactly
3. Verify chain support - New chains may not be immediately available

PMM/RFQ Errors

These errors occur when the route includes PMM (Private Market Maker) or RFQ (Request for Quote) sources such as Hashflow, Bebop, Native, or limit orders. They are returned during the build-route step when the maker fails to provide a firm quote.

Error Categories

General Handling Methods

1. Retry with a fresh route - Most PMM/RFQ errors are transient. Call get-route again to get fresh indicative prices, then build-route. Stale routes are the most common cause of failures.
2. Exclude the failing source - Use excludedSources to skip the problematic maker (e.g., excludedSources=hashflow,bebop). The router will find routes through other liquidity sources.
3. Adjust trade amount - If you hit min/max size errors, increase or decrease amountIn accordingly. For "gas exceeds size" errors, increase the trade to make it economically viable.
4. Increase slippage tolerance - For market-movement and slippage errors, a higher slippage tolerance gives the maker more room. Alternatively, just retry quickly before the price moves further.
5. Wait and retry for rate limits - For rate limit errors, back off for a few seconds before retrying.
6. Use a different wallet for blacklist errors - Blacklist/banned errors mean the maker has blocked your address. There is no workaround other than using a different sender address.
7. Don't self-fill limit orders - For ErrSameSenderMaker, use a different wallet than the one that created the limit order.

Pre-Transaction Errors

These errors occur after successfully calling the Get Route and Build Route APIs, but before the transaction lands on-chain. The user's wallet or RPC node fails to estimate gas or submit the transaction.

Flow where these errors occur:

Get Route API ✓ → Build Route API ✓ → Wallet/RPC Submission ✗ (fails here)

Gas Estimation Failed / Cannot Estimate Gas

Description: The wallet or RPC node failed to estimate gas for the transaction. The transaction was never broadcast to the network.

Common Causes:

• RPC node is overloaded, rate-limited, or experiencing issues
• Route has become stale (pool states changed since route was fetched)
• Price moved beyond slippage tolerance since route was built
• Network congestion causing RPC timeouts
• Token contract has transfer restrictions or blacklists

Solutions:

1. Retry the transaction - Transient RPC issues often resolve on retry
2. Fetch a fresh route - The route may be stale; call Get Route and Build Route again
3. Change RPC URL - Switch to a different RPC provider (e.g., Alchemy, Infura, QuickNode, or chain's public RPC)
4. Check RPC rate limits - If using a free RPC, you may be rate-limited; use a paid tier or different provider

Transaction Submission Failed

Description: Gas estimation succeeded, but the transaction failed to be broadcast to the network.

Common Causes:

• RPC node rejected the transaction
• Nonce issues (pending transactions blocking new ones)
• Insufficient ETH/native token for gas fees
• Network connectivity issues
• RPC provider downtime

Solutions:

1. Check gas balance - Ensure sufficient native token (ETH, MATIC, etc.) for gas fees
2. Reset nonce - If stuck transactions exist, cancel them or reset wallet nonce
3. Try a different RPC - Switch RPC provider to rule out provider-specific issues
4. Wait and retry - Network congestion may clear up
5. Check wallet connection - Ensure wallet is properly connected to the correct network

Simulation Revert

Description: The transaction simulation indicates it would revert on-chain.

Common Causes:

• Insufficient token balance
• Insufficient token approval
• Route expired (stale route data)
• Price moved beyond slippage tolerance
• Token has transfer fees or restrictions

Solutions:

1. Verify balance - Ensure sender has at least amountIn of the input token
2. Check approval - Approve routerAddress to spend at least amountIn
3. Fetch fresh route - Re-call Get Route and Build Route immediately before executing
4. Increase slippage - Use higher slippageTolerance (e.g., from 50 to 100 for 1%)
5. Check token restrictions - Some tokens have transfer fees, blacklists, or max transaction limits

On-Chain Errors (Transaction Reverts)

These errors occur when a submitted transaction reverts on the blockchain.

Diagnosing On-Chain Reverts

When a transaction reverts, use these tools to decode the revert reason:

Using Foundry cast run (recommended — requires archive node):

cast run {txHash} --rpc-url {RPC_URL}

This replays the transaction and shows the full execution trace, including the exact revert reason and the internal call that failed.

Using Foundry cast call at historical block (alternative):

cast call \
  --rpc-url {RPC_URL} \
  --from {sender} \
  --value {tx.value} \
  --block {blockNumber} \
  {tx.to} \
  {tx.data}

Replays the call at the block where it reverted. Requires archive node.

Using ethers.js (for non-Foundry environments):

const provider = new ethers.JsonRpcProvider(RPC_URL);
const tx = await provider.getTransaction(txHash);
const receipt = await provider.getTransactionReceipt(txHash);

try {
  await provider.call(
    { from: tx.from, to: tx.to, data: tx.data, value: tx.value },
    receipt.blockNumber
  );
} catch (error) {
  console.log("Revert reason:", error.reason || error.message);
}

Using block explorer (no tools needed): Check the transaction on the chain's block explorer (e.g., etherscan.io). Most explorers decode common revert reasons automatically and show them in the transaction details under "Revert Reason" or "Status".

Note: cast run and historical cast call require an archive node. Public RPCs often only keep recent state. If you get "missing trie node" errors, use an archive-enabled RPC provider (Alchemy, QuickNode, etc.) or check the block explorer instead.

Use the /swap-status skill for a guided diagnosis workflow that automates these steps.

TransferHelper: TRANSFER_FROM_FAILED

Description: The router contract failed to transfer tokens from the sender.

Common Causes:

• Insufficient token approval for router contract
• Insufficient token balance in sender wallet

Solutions:

1. Check balance: Ensure sender has at least amountIn of the input token
2. Check approval: Approve routerAddress to spend at least amountIn.

   token.approve(routerAddress, amountIn)
   

TransferHelper: ETH_TRANSFER_FAILED

Description: Native ETH transfer failed during the swap.

Common Causes:

• Insufficient ETH balance for swap + gas
• Contract recipient rejects ETH transfers
• Recipient is a contract without receive/fallback function

Solutions:

1. Check ETH balance: Ensure sufficient ETH for both amountIn and gas fees
2. Verify recipient: If recipient is a contract, ensure it can receive ETH
3. Check transactionValue: Send exactly the transactionValue from build response

Return Amount Is Not Enough (InsufficientAmountOut)

Description: The actual output amount is less than the minimum required based on slippage settings.

Common Causes:

• Price moved unfavorably between quote and execution
• High price volatility
• Slippage tolerance too tight
• Large trade causing price impact
• MEV/sandwich attack

Solutions:

1. Increase slippage tolerance:

   {"slippageTolerance": 100}  // 1%
   

2. Re-fetch route: Get fresh quote immediately before executing
3. Reduce trade size: Smaller trades have less price impact
4. Use private RPC: Submit through Flashbots or private mempool to avoid MEV

Out of Gas

Description: The transaction reverted because it consumed all allocated gas before completing the swap. The EVM stops execution when the gas limit is reached, causing the entire transaction to fail and revert.

Common Causes:

• Gas limit too low: The gas limit set when submitting the transaction is lower than the actual gas needed for the swap path
• Complex route: Multi-hop routes or routes through many pools require more gas than simple single-hop swaps
• Underestimation: Gas estimation (e.g. from eth_estimateGas or the build response) was inaccurate due to state change or edge case
• Wallet/SDK default: The client overwrites the suggested gas limit with a conservative default that is too low for aggregator routes

Solutions:

1. Use suggested gas and add buffer: Take the gas or gas estimate from the build response and multiply by 1.2–1.3 (20–30% buffer) when submitting the transaction
2. Do not cap gas limit: If your app or wallet caps gas limit, allow a higher cap for KyberSwap routes
3. Check integration: Ensure your code passes through the gas limit from the build response instead of replacing it with a fixed or default value
4. Re-fetch route: A different route might use fewer hops and less gas; try building again

Call Failed (Internal Liquidity Source Error)

Description: An internal call to a liquidity source (DEX pool) failed.

Common Causes:

• Pool state changed between quote and execution
• Pool has insufficient liquidity
• Pool contract is paused or malfunctioning
• Route included a deprecated pool

Solutions:

1. Wait and retry: Pool state may stabilize
2. Re-fetch route: Get a fresh route that may use different pools
3. Exclude problematic source: Use excludedSources to skip the failing DEX
4. Reduce trade size: May route through more stable pools

Unlisted Error Codes

For any error code not documented above, show the raw code and message from the API response to the user and suggest:

1. Re-fetch the route and retry
2. Check the official KyberSwap API docs: https://docs.kyberswap.com/kyberswap-solutions/kyberswap-aggregator/aggregator-api-specification/evm-swaps