Skip to main content

​
Error classes

Every error thrown by the SDK is an instance of OneSwapError: 
import {
  ConflictError,    // 409 — active intent or other request conflict
  AmbiguousPoolPairError, // 409 — token pair maps to multiple pools
  AuthError,        // 401 — invalid or missing API key or wallet token
  ValidationError,  // 400 — bad parameters
  NotFoundError,    // 404 — pool/intent/party not found
  RateLimitError,   // 429 — too many requests
  SlippageError,    // swap output below minimum
  PriceImpactError, // created swap later hit price_impact_exceeded during wait()
  InsufficientLiquidityError, // swap refunded because the pool was too thin
  InsufficientAmountError, // swap refunded because input was below traffic cost
  OutputFailedError,// swap output transfer failed
  SwapFailedError,  // generic terminal swap failure
  RefundFailedError,// swap refund failed
  ExpiredError,     // intent expired before completion
  NetworkError,     // transport-level failure before an HTTP response
  TimeoutError,     // request timeout
  ServerError       // 500 — something went wrong on our end
} from '@oneswap/sdk'

​
Handling swap errors

try {
  const swap = await client.swaps.create({ ... })
  const result = await swap.wait()
} catch (err) {
  if (err instanceof SlippageError) {
    console.log('Swap refunded due to slippage')
  } else if (err instanceof PriceImpactError) {
    console.log('Swap rejected — price impact exceeds the maximum allowed')
  } else if (err instanceof InsufficientLiquidityError) {
    console.log('Swap refunded due to insufficient liquidity')
  } else if (err instanceof InsufficientAmountError) {
    console.log('Swap refunded because the input amount was too small')
  } else if (err instanceof OutputFailedError) {
    console.log('Swap payout failed — inspect the terminal intent status')
  } else if (err instanceof RefundFailedError) {
    console.log('Swap refund failed — manual intervention is required')
  } else if (err instanceof SwapFailedError) {
    console.log('Swap failed — inspect the intent before retrying')
  } else if (err instanceof ExpiredError) {
    console.log('Swap expired or was cancelled before completion')
  } else if (err instanceof AmbiguousPoolPairError) {
    console.log(err.candidates)
  } else if (err instanceof ConflictError) {
    console.log(err.message)
  } else if (err instanceof AuthError) {
    console.log('Check your API key and repeat wallet authentication if needed')
  } else if (err instanceof ValidationError) {
    console.log(err.message)
  } else if (err instanceof TimeoutError || err instanceof NetworkError) {
    console.log(err.message)
  }
}
PriceImpactError is raised by swap.wait() after a created intent reaches terminal status price_impact_exceeded. Quote-time or create-time price-impact rejections are plain ValidationError responses because the API returns HTTP 400.

​
Error properties

All errors have: 
err.message    // human-readable description
err.statusCode // HTTP status (0 for lifecycle or transport errors)
err.response   // raw response body from the API
AmbiguousPoolPairError also exposes err.candidates, which lists the matching pools and token admins you can use to retry with poolId, fromAdmin, or toAdmin.

​
Common scenarios

ErrorWhenWhat to do
AmbiguousPoolPairErrorThe same token symbols exist under multiple adminsRetry with poolId or both token admin fields
ConflictErrorAnother active swap intent already exists for this wallet, pool, and input tokenReuse, cancel, or wait for the existing intent before creating another
AuthErrorAPI key is wrong, missing, or the wallet token is invalid/expiredCheck your key and refresh wallet auth
ValidationErrorBad params or preflight validation failed (missing field, invalid amount, token/pool mismatch)Fix the request
NotFoundErrorPool or intent doesn’t existCheck the ID
RateLimitErrorToo many requestsBack off and retry
SlippageErrorPrice moved during swapRetry with higher tolerance or try again
PriceImpactErrorAn already-created swap later reached terminal status price_impact_exceeded during executionReduce swap size or add liquidity to the pool before retrying
InsufficientLiquidityErrorThe pool could not fill the swapRetry later or reduce size
InsufficientAmountErrorA created swap was refunded because the live traffic cost exceeded the depositIncrease the amount and create a new intent
OutputFailedErrorOutput payout failed or the swap party had no output holdingsInspect the terminal intent status before retrying
SwapFailedErrorThe swap reached a generic terminal failure stateInvestigate the intent before retrying
RefundFailedErrorThe refund path failed after a swap errorManual intervention is required
ValidationError (400)Quote or intent creation failed because price impact already exceeded the server capReduce swap size or add liquidity before retrying
ValidationError (400)Quote or intent creation failed because the amount was below the estimated traffic costIncrease the swap amount. The error response includes minimumAmount.
ExpiredErrorThe swap intent expired after its current 24-hour deposit window, or swap.wait() observed a cancelled intentCreate a new intent if needed
TimeoutErrorThe SDK request timed out before the API repliedRetry the request or increase timeout
NetworkErrorThe request failed before an HTTP response was receivedRetry after checking connectivity
ServerErrorOur problemRetry after a moment

​
Configuring wait behavior

const result = await swap.wait({
  pollInterval: 5000,   // check every 5 seconds (default: 3s)
  timeout: 600000       // give up after 10 minutes (default: 35min)
})