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
| Code | Status | What to do |
|---|---|---|
below_tolerance | 422 | The 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_peg | 422 | The 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_liquidity | 422 | refusalReason: 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_coin | 422 | One side is on our exclusion list and is not quoted at any size. Not retryable. |
no_reference_rate | 422 | A cross-currency pair, and we hold no rate between the two currencies right now, so the quote cannot be judged. Retry later. |
not_a_stablecoin | 400 | One 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_tolerance | 400 | maxParDeviationBps must be above 0 and at most 100. |
no_route | 400 | The pair cannot be routed at this size. Not retryable as it is. |
idempotency_key_reused | 422 | This 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.