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:

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

Error Handling Workflow

Follow this systematic approach when debugging swap failures:

Step 1: Identify Error Phase

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

Step 2: Look Up Error in This Guide

Find the error code (e.g., 4008, 4222, 4227) in the API response
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
Read the Description, Common Causes, and Solutions for your specific error
Follow the recommended solutions in order

Common Quick Fixes

Symptom	Quick Fix
Route not found	Remove source filters, try smaller amount
Token not found	Verify address, check chain
Insufficient output	Increase slippage
Transfer failed	Check balance and approval
Request timeout	Retry, check network
Gas estimation failed (4227)	Refetch route and retry, or use `suggestedSlippage` (not recommended)
Quoted < estimated (4222)	Fetch fresh route, or exclude RFQ sources
Slippage invalid	Set `ignoreCappedSlippage: true` (not recommended)

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:

Field	Description	Cause
`tokenIn`	`required`	Missing tokenIn parameter
`tokenIn`	`invalid`	Wrong length, uppercase `0X`, missing `0x` prefix, non-hex chars
`tokenIn`	`identical with tokenOut`	Same token for input and output
`tokenOut`	`required`	Missing tokenOut parameter
`amountIn`	`invalid`	Zero, negative, decimal, scientific notation (1e18), hex (0x...)
`feeAmount`	`invalid`	Float value instead of integer
`gasPrice`	`invalid`	Non-numeric value
`chargeFeeBy`	`invalid`	Value other than `currency_in` or `currency_out`
`deadline`	`in the past`	Unix timestamp before current time
`slippageTolerance`	`invalid`	Negative value, or > 2000 without `ignoreCappedSlippage` (build only)
`recipient`	`required`	Missing recipient in build request
`route.route`	`empty route`	Empty or null route array in routeSummary
`to`	`required`	Missing `to` parameter in route/build endpoint

Solutions:

Read the fieldViolation and description in the API response to see which field failed and the root cause.
For address-related fields: use valid 42-character hex strings with lowercase 0x prefix (not 0X)
For amount-related fields: use valid integer strings in wei - no decimals, no scientific notation, no hex
For deadline: use a Unix timestamp in the future (past timestamps are invalid)
For slippageTolerance in build: keep under 2000, or set ignoreCappedSlippage: true
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:

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:

Ensure that deadline and slippageTolerance are Numbers. enableGasEstimation and ignoreCappedSlippage are booleans (true or false)
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:

Try to re-fetch the route after a period of time (recommended)
Use excludedSources to skip the failing DEX
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:

Add a valid feeReceiver address - Provide the wallet address that should receive the fees
Match fee arrays - When using multiple receivers, ensure feeAmount and feeReceiver have the same number of comma-separated values
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:

Reduce feeAmount to be less than amountIn
If using BPS (isInBps: true), verify calculation: 10 = 0.1%, 100 = 1%
When not using BPS, feeAmount is in token wei - ensure it's less than amountIn
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:

Reduce feeAmount to be less than expected amountOut
If using BPS (isInBps: true), verify calculation: 10 = 0.1%, 100 = 1%
When not using BPS, feeAmount is in token wei - ensure it's less than amountOut
Consider switching to chargeFeeBy: "currency_in" for predictable fee calculation
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:

Verify both tokens are valid and tradeable on this chain
Remove source filters to search all liquidity sources
Try a different chain if the token is multi-chain
Reduce trade size - some routes only work for smaller amounts
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:

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:

Remove or adjust source filters
Reduce trade size to fit available liquidity
Try without onlyDirectPools or onlySinglePath restrictions
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:

Verify the token contract address on a block explorer
Ensure you're using the correct chain
Check token address checksums (case-sensitive for EIP-55)
For native tokens, use: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
For newly deployed tokens, wait for indexing
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:

Fetch new route and retry the request - Stale routes can cause failures (recommended)
Use excludeRFQSources: true - Avoid RFQ sources and rely only on AMM pools for more consistent pricing
Use onlyScalableSources: true - Stick to pools with predictable, calculable pricing
Reduce trade size - Smaller amounts typically get better and more stable quotes
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:

Fetch a new route and retry - The route is stale; get a fresh quote (recommended)
Use the suggestedSlippage value - The API returns a suggested slippage (e.g., 230 = 2.3%) that would work
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:

Check sender's native token balance - Ensure the sender address has enough native token to cover the full transaction value plus gas fees
Reduce the swap amount - Lower amountIn to leave room for gas fees
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:

Check token approval - Ensure the sender has approved the routerAddress to spend at least amountIn of the input token
Check token balance - Ensure the sender holds at least amountIn of the input token
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:

Provide a valid sender address - Include the sender parameter with the user's wallet address
Disable gas estimation - If you don't need gas costs, set enableGasEstimation: false (or omit it)
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:

Remove includedSources and excludedSources parameters
Expand the list of included sources
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:

Use the wrapped native token address directly instead of native token address
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:

Retry the request
Check network connectivity
Try during lower traffic periods
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:

Verify all addresses - Ensure all address fields are valid 42-character hex strings starting with 0x
Don't modify routeSummary - Pass the routeSummary exactly as returned from get route API
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:

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
Check spelling - Chain names are lowercase and must match exactly
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

Category	Errors	Cause
Blacklist / Banned	`ErrFirmQuoteBlacklist`, `ErrAddressBanned`, `ErrRFQDenyListed`, `ErrRFQBlacklisted`	Sender address is on the maker's deny list
Insufficient Liquidity	`ErrFirmQuoteInsufficientLiquidity`, `ErrRFQInsufficientLiquidity`, `ErrEmptyOrderList`	Maker doesn't have enough balance or pulled liquidity
Amount Too Small	`ErrMinGreaterExpect`, `ErrOrderIsTooSmall`, `ErrRFQMinSize`, `ErrRFQBelowMinimumAmount`	Trade amount is below the maker's minimum
Amount Too Large	`ErrRFQExceedsSupportedAmounts`	Trade amount exceeds the maker's maximum
Market Moved	`ErrFirmQuoteMarketCondition`, `ErrQuotedAmountSmallerThanEstimated`	Price changed between get-route and build-route
Slippage	`ErrAmountOutLessThanMin(4227)`	Firm quote output is below minimum acceptable amount
Rate Limited	`ErrRFQRateLimit`	Too many requests to the maker
Pair Not Supported	`ErrRFQNoMakerSupports`, `ErrRFQTokenNotSupported`	Maker doesn't support this token pair
Volatility	`ErrRFQMarketsTooVolatile`	Maker refuses to quote due to high volatility
Timeout	`ErrRFQTimeout`	Maker didn't respond in time
Same Sender/Maker	`ErrSameSenderMaker`	Taker and limit order maker are the same address
Generic Failure	`ErrRFQFailed`, `ErrFirmQuoteFailed`, `ErrQuoteSignFailed`, etc.	Catch-all failures from various makers

General Handling Methods

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.
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.
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.
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.
Wait and retry for rate limits - For rate limit errors, back off for a few seconds before retrying.
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.
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:

Retry the transaction - Transient RPC issues often resolve on retry
Fetch a fresh route - The route may be stale; call Get Route and Build Route again
Change RPC URL - Switch to a different RPC provider (e.g., Alchemy, Infura, QuickNode, or chain's public RPC)
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:

Check gas balance - Ensure sufficient native token (ETH, MATIC, etc.) for gas fees
Reset nonce - If stuck transactions exist, cancel them or reset wallet nonce
Try a different RPC - Switch RPC provider to rule out provider-specific issues
Wait and retry - Network congestion may clear up
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:

Verify balance - Ensure sender has at least amountIn of the input token
Check approval - Approve routerAddress to spend at least amountIn
Fetch fresh route - Re-call Get Route and Build Route immediately before executing
Increase slippage - Use higher slippageTolerance (e.g., from 50 to 100 for 1%)
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.

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:

Check balance: Ensure sender has at least amountIn of the input token
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:

Check ETH balance: Ensure sufficient ETH for both amountIn and gas fees
Verify recipient: If recipient is a contract, ensure it can receive ETH
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:

Increase slippage tolerance:
```
{"slippageTolerance": 100}  // 1%
```
Re-fetch route: Get fresh quote immediately before executing
Reduce trade size: Smaller trades have less price impact
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:

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
Do not cap gas limit: If your app or wallet caps gas limit, allow a higher cap for KyberSwap routes
Check integration: Ensure your code passes through the gas limit from the build response instead of replacing it with a fixed or default value
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:

Wait and retry: Pool state may stabilize
Re-fetch route: Get a fresh route that may use different pools
Exclude problematic source: Use excludedSources to skip the failing DEX
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:

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

error-handling

KyberSwap Error Handling Skill

When to use

Error Categories

Error Handling Workflow

Step 1: Identify Error Phase

Step 2: Look Up Error in This Guide

Common Quick Fixes

Best Practices

Route Freshness

Slippage Configuration

Rate Limiting

API Errors Reference

Error 4000: Bad Request

Error 4001: Query Parameters Malformed

Error 4002: Request Body Malformed

Error 4003: Invalid Swap

Error 4004: Invalid config for fee receiver

Error 4005: Fee Amount Greater Than Amount In

Error 4007: Fee Amount Greater Than Amount Out

Error 4008: Route Not Found

Error 4009: Amount In Exceeds Maximum

Error 4010: No Eligible Pools

Error 4011: Token Not Found

Error 4222: Quoted Amount Smaller Than Estimated

Error 4227: Gas Estimation Failed

Variant 1: "return amount is not enough"

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

Variant 3: "TransferHelper: TRANSFER_FROM_FAILED"

Error 40010: Empty sender address

Error 40011: Filtered Liquidity Sources

Error 4221: WETH Not Configured

Error 4990: Request Canceled

Error 500: Internal Server Error

HTTP 404: Chain Not Found

PMM/RFQ Errors

Error Categories

General Handling Methods

Pre-Transaction Errors

Gas Estimation Failed / Cannot Estimate Gas

Transaction Submission Failed

Simulation Revert

On-Chain Errors (Transaction Reverts)

TransferHelper: TRANSFER_FROM_FAILED

TransferHelper: ETH_TRANSFER_FAILED

Return Amount Is Not Enough (InsufficientAmountOut)

Out of Gas

Call Failed (Internal Liquidity Source Error)

Unlisted Error Codes