Skip to content
Stablecoin refusals

LCX Liberty. American DeFi. Your keys. Your assets. Your control.

Stablecoin API

Stablecoin refusals

Every code the Stablecoin API refuses with, and what to do about each.

The shape of a refusal

A refusal is the API's usual error envelope (see Errors): success: false, a code to branch on and a message written to be shown. Where a rule refused the quote, refusalReason names it, and the fields that explain it travel beside it.

json
{
  "success": false,
  "code": "below_tolerance",
  "refusalReason": "below_tolerance",
  "message": "This quote pays -62.40 bps from par, beyond the 50 bps allowed (maxParDeviationBps). A smaller amount may fill within it.",
  "parDeviationBps": -62.4,
  "maxParDeviationBps": 50
}
json
{
  "success": false,
  "code": "insufficient_liquidity",
  "refusalReason": "below_floor",
  "message": "This pair is indexed, but our liquidity is too thin at this size…",
  "fillsUpTo": "4200000000000"
}

fillsUpTo is the largest amount the engine verified it can fill, in base units of tokenIn. It can be absent when no size fills.

Codes

CodeStatusWhat to do
below_tolerance422The quote is further from the anchor than maxParDeviationBps allows. The body carries parDeviationBps and maxParDeviationBps. Send a smaller amount, or a wider tolerance (at most 100).
off_peg422The coin you are buying trades more than 1% away from its peg. Set allowOffPeg: true only if you mean to buy it anyway; the tolerance still applies.
insufficient_liquidity422refusalReason: below_floor. Routable, but not at this size within the floor. fillsUpTo, when present, is the largest amount that fills, in base units of tokenIn. Send that or less, or split the amount.
excluded_coin422One side is on our exclusion list and is not quoted at any size. Not retryable.
no_reference_rate422A cross-currency pair, and we hold no rate between the two currencies right now, so the quote cannot be judged. Retry later.
not_a_stablecoin400One side is not in the registry for that chain. GET /v1/stablecoins/coins lists what is. /v1/quote routes any token, without these rules.
bad_tolerance400maxParDeviationBps must be above 0 and at most 100.
no_route400The pair cannot be routed at this size. Not retryable as it is.
idempotency_key_reused422This Idempotency-Key was sent with a different body in the last 24 hours. Use a new key for a new request.

Handling them

ts
const body = await res.json();
if (!body.success) {
  switch (body.code) {
    case "below_tolerance":
      // body.parDeviationBps: how far from par the market is at this size.
      return offerSmallerAmount(body.parDeviationBps, body.maxParDeviationBps);
    case "insufficient_liquidity":
      // body.fillsUpTo, when present, is the most that fills (base units of tokenIn).
      return body.fillsUpTo ? offerAmount(body.fillsUpTo) : tellUser(body.message);
    case "off_peg":
      // Do not set allowOffPeg on a user's behalf: it is their decision to buy below the peg.
      return tellUser(body.message);
    default:
      throw new Error(`${body.code}: ${body.message}`);
  }
}

Sending the same request again at once gets the same answer. Change the amount or the tolerance, or for no_reference_rate, wait. Everything else, from RATE_LIMITED to decimals_mismatch, means what it means on the swap API; see Errors.