Swap error handling

Errors the App Kit SDK throws for Swap are KitError instances, exported from @circle-fin/app-kit. Its structured fields let you branch on the failure type instead of parsing message strings. Errors surface from kit.estimateSwap and kit.swap.

`KitError` fields

Field	Description
`code`	Numeric identifier (for example, `5002`).
`name`	Stable string identifier for exact matching, logging, and telemetry.
`type`	Classifies the failure (see Error types).
`recoverability`	`FATAL` (don’t retry) or `RETRYABLE` (back off and retry). `RESUMABLE` is defined on `KitError` but not currently used by Swap errors.
`message`	Human-readable diagnostic. Not suitable for end-user display without review.
`cause`	The underlying error, if one was wrapped.

Check code or name for specific handling, type for handling a whole category, and recoverability to decide whether to retry.

Error types

Type	Origin	Typical recoverability
`INPUT`	Parameter validation, unsupported blockchain or token.	`FATAL`
`ONCHAIN`	Swap execution simulation or transaction reverted onchain.	`FATAL`
`BALANCE`	Insufficient token, gas, or allowance (surfaced from the wallet adapter).	`FATAL`
`RPC`	Blockchain RPC issues during execution (surfaced from the wallet adapter).	`RETRYABLE`
`NETWORK`	Connectivity or timeout reaching the Swap service.	`RETRYABLE`
`RATE_LIMIT`	Request throttled (HTTP 429).	`RETRYABLE`
`SERVICE`	Swap service backend failure.	`RETRYABLE`
`LIQUIDITY`	The routing provider can’t fill the requested size right now.	`RETRYABLE`
`UNKNOWN`	Unrecognized error.	`FATAL`

Common error codes

Code	Name	Type	When it fires
`1003`	`INPUT_UNSUPPORTED_ROUTE`	`INPUT`	No route exists for the token pair, blockchains, and amount. See No route available.
`1009`	`INPUT_SLIPPAGE_CONSTRAINT_NOT_MET`	`INPUT`	A route exists but not within the slippage tolerance or stop limit. Raise `slippageBps` or adjust `stopLimit`.
`1013`	`INPUT_AMOUNT_OUT_OF_RANGE`	`INPUT`	The amount is outside the routing provider’s minimum or maximum. `cause.trace` includes `minAmount` or `maxAmount`.
`1098`	`INPUT_VALIDATION_FAILED`	`INPUT`	Swap parameters failed validation. Fix the inputs; retrying unchanged won’t help.
`5001`	`ONCHAIN_TRANSACTION_REVERTED`	`ONCHAIN`	The swap transaction reverted after submission.
`5002`	`ONCHAIN_SIMULATION_FAILED`	`ONCHAIN`	The swap execution simulation reverted onchain. See Simulation failures on Arc testnet.
`6001`	`LIQUIDITY_INSUFFICIENT`	`LIQUIDITY`	A route exists, but the routing provider can’t fill the requested size right now. Reduce the amount or try again later.

Handling errors

Catch a KitError and branch on code, type, and recoverability:

TypeScript

import {
  isKitError,
  isRetryableError,
  getErrorCode,
} from "@circle-fin/app-kit";

try {
  const result = await kit.swap({
    from: { adapter, chain: "Arc_Testnet" },
    tokenIn: "USDC",
    tokenOut: "EURC",
    amountIn: "1.00",
  });
} catch (err) {
  if (isKitError(err)) {
    const code = getErrorCode(err);
    if (code === 1009 || code === 5001 || code === 5002) {
      // Price moved past the tolerance or the swap reverted: raise slippageBps. See below.
      return retryWithHigherSlippage();
    }
    if (err.type === "LIQUIDITY") {
      // Retrying the same size won't help until liquidity returns
      return promptForSmallerAmount();
    }
    if (isRetryableError(err)) {
      // Rate limits, network, and service failures: back off and retry
      return scheduleRetry();
    }
    if (err.type === "INPUT") {
      // `message` is a diagnostic — review it before showing it to end users
      console.error(`Swap input error: ${err.message}`);
      return;
    }
  }
  throw err;
}

Simulation failures on Arc testnet

Because Arc testnet liquidity is thin, kit.estimateSwap can succeed while the swap itself fails with one of these errors:

INPUT_SLIPPAGE_CONSTRAINT_NOT_MET (1009) when the route is quoted.
ONCHAIN_SIMULATION_FAILED (5002) when kit.swap reverts during onchain simulation.
ONCHAIN_TRANSACTION_REVERTED (5001) after the transaction is submitted.

To resolve the failure, raise the slippage tolerance above the 300 bps default (for example, 1000 bps):

TypeScript

const result = await kit.swap({
  from: { adapter, chain: "Arc_Testnet" },
  tokenIn: "USDC",
  tokenOut: "EURC",
  amountIn: "1.00",
  config: {
    slippageBps: 1000, // Raise the tolerance above the 300 bps default
  },
});

To set a stop limit instead of a slippage tolerance, see Set slippage tolerance or stop limit.

No route available

Routing failures surface in three ways:

INPUT_UNSUPPORTED_ROUTE (1003): the routing layer found no route for the token pair, blockchains, and amount you requested. Change the amount or pick a different token pair, since retrying the same request won’t help.
INPUT_SLIPPAGE_CONSTRAINT_NOT_MET (1009): a route exists but not within your slippage tolerance or stop limit. Raise slippageBps or adjust stopLimit.
“No quotes available”: a message from the routing provider itself, not the SDK, so you only see it when calling the provider’s API directly. This isn’t a supported integration path, and direct provider calls are rate limited. Route quotes through kit.estimateSwap. If you’re hitting rate limits through the SDK itself, pass a Circle API key in the swap config.

Send

Bridge

Swap

Unified Balance

Onramp

Earn

Borrow

Swap error handling

`KitError` fields

Error types

Common error codes

Handling errors

Simulation failures on Arc testnet

No route available

​KitError fields

​Error types

​Common error codes

​Handling errors

​Simulation failures on Arc testnet

​No route available

`KitError` fields

Error types

Common error codes

Handling errors

Simulation failures on Arc testnet

No route available