Skip to main content

Error Codes

Details​

When a request fails, the API answers with an RFC 7807 problem details object. The detail field carries a human-readable explanation. Because we reserve the right to reword that text, failures that originate upstream (the Chainflip quoting service or broker) also carry a code field: a stable, machine-readable identifier your client can branch on. Codes also exist for conditions the API classifies locally, such as the swap status lookups. The HTTP status follows the code: a request Chainflip rejects as unfulfillable answers 400, a temporary upstream condition answers 503, a status lookup with nothing (yet) to answer with answers 404, and only unclassified failures answer 500.

{
"type": "https://tools.ietf.org/html/rfc9110#section-15.6.4",
"title": "Service Unavailable",
"status": 503,
"detail": "One of the assets in this swap is currently disabled on Chainflip",
"traceId": "00-6e04726aca44787669d57a48b1833007-ddd09a1fe1f24426-00",
"code": "asset_disabled"
}

code is a top-level member next to title, status and detail. It is always lowercase snake_case. Codes are contract: once published, a code is never renamed or reused with a different meaning. New codes may be added over time.

Where code appears​

code is emitted on the failure responses of:

  • Asking for a Quote (/quotes, /quotes-native, and the deprecated /quote, /quote-native)
  • Starting a Swap (/swap, both GET and POST)
  • The vault swap transaction payload endpoints (/tx-payload/bitcoin, /tx-payload/evm, /tx-payload/solana, /tx-payload/tron)
  • The swap status lookups (Get Swap Status) (/status-by-id, /status-by-deposit-channel, /status-by-transaction-hash)

It is not present on:

  • Plain input validation failures, which use the validation problem details shape with an errors object and no code (for example chunkIntervalBlocks without numberOfChunks). Parameter values Chainflip's own node rejects and that cannot be adjusted are coded 400 ProblemDetails instead. Both are HTTP 400, so on a 400 check for code before assuming an errors object.
  • Route denial on /swap (HTTP 403 when a pair is not enabled for your account). Only the quote endpoints carry route_disabled.
  • Failures the API could not classify, for example a provider timing out or throwing unexpectedly. These return the same problem details shape with no code member.
  • The dashboard and the MCP endpoint.

Handling code in your client​

  • Treat code as optional. When it is absent, the member is omitted entirely; it is never null or an empty string. Fall back to status and detail.
  • Treat unknown values as "some other failure". New codes will be added without notice; do not fail hard on a value you do not recognise.
  • Do not branch on detail. That text can change.
  • Use status for the coarse decision and code for the fine one. 400 means the request as sent will not succeed (change the amount or the pair). 503 means the condition is temporary (retry later, with backoff); a safe-mode pause can last until Chainflip lifts it, and /health's chainflip-safe-mode entry names the blocked flags. 500 means something unexpected happened on our side or upstream.
  • Do not retry a 400 unchanged. A 503 is safe to retry, but retrying chainflip_safe_mode only helps once the pause ends.
  • On the status lookups, a 404 carries a code: swap_pending means the swap exists but its status has not been written yet — poll again shortly. swap_unknown usually means a wrong key, but it is not a permanent stop-polling signal: on a deposit transaction hash it can clear once the deposit has been witnessed on-chain. Retry with backoff and stop at your own deadline.

Catalogue​

codeHTTP statusApplies toMeaning
amount_below_minimum400quoteThe input amount does not cover the ingress fee. Try a bigger amount.
egress_below_minimum400quoteThe output would be under the destination chain's minimum egress amount, usually because of high gas prices. Try a bigger amount.
egress_fee_not_covered400quoteThe output would not cover the egress fee, usually because of high gas prices. Try a bigger amount.
insufficient_liquidity400quoteNo quote is available for this amount. Try a lower amount. On the deprecated /quote and /quote-native, it also means only a DCA quote is available; /quotes and /quotes-native return it.
live_price_protection_unavailable400swap, vault payloadChainflip's broker refused livePriceSlippageTolerancePercent because an asset of the pair has no oracle price on Chainflip (FLIP, for example). This is rare: normally the parameter is omitted for such a pair and the swap proceeds with Chainflip's default protection; the code answers only when that check was unavailable. No channel was opened and no payload was built; omit the parameter or choose another pair.
invalid_refund_parameters400swap, vault payloadChainflip's node rejected the refund parameters. This is rare: a retryDurationInBlocks above the current runtime limit is lowered to Chainflip's maximum instead, so the code is used when that limit cannot be read or the node rejects the refund parameters for another reason. The detail carries the node's reason. No channel was opened and no payload was built; retrying unchanged fails the same way.
invalid_dca_parameters400swap, vault payloadChainflip's node rejected the DCA parameters. This is rare: a schedule longer than the current runtime limit is shortened instead, so the code is used when that limit cannot be read or Chainflip refuses the schedule for another reason. The detail carries the node's reason. No channel was opened and no payload was built; retrying unchanged fails the same way.
quoting_maintenance503quote, swap, vault payloadChainflip quoting is in maintenance mode. Retry later.
swapping_maintenance503quote, swap, vault payloadThe Chainflip swap service is in maintenance mode. Retry later.
deposit_channel_failed503quote, swap, vault payloadThe broker could not open a deposit channel. Retry later.
too_many_channels503quote, swap, vault payloadChainflip's open channel cap has been hit. Retry later.
asset_disabled503quote, swap, vault payloadChainflip has switched one of the assets off upstream. Nothing about the amount or route will fix it; retry later or choose another asset.
chainflip_safe_mode503swap, vault payloadChainflip's safe mode has paused swapping or deposits for the source chain. No deposit channel was opened and no payload was built; retrying only helps once governance lifts the pause. /health's chainflip-safe-mode entry names the blocked flags.
upstream_error500quote, swap, vault payloadAn upstream failure the API could not classify further.
provider_unavailable503quoteNo healthy quote provider is available right now (for example every circuit breaker is open). Retry later.
route_disabled403quoteThe pair is not enabled for your account. Enable it in your dashboard route configuration, or pick another pair.
swap_unknown404statusNo swap is recorded under this API key for this lookup key (yet) — usually a wrong key, but not terminal: on a transaction hash it can clear once the deposit is witnessed on-chain.
swap_pending404statusThe swap exists but its status is not available yet (the first poll has not written it). Poll again shortly.

"quote, swap, vault payload" means the code can appear on any of those endpoints, because they all map the same upstream error text. In practice the amount- and liquidity-related codes are mostly seen on quotes, and the channel-related codes on swaps. The status codes are different in kind: they are the API's own lookup results, not mapped upstream text.

Example​

tip

Want to test first? Change the API base URL to https://perseverance.chainflip-broker.io. The Testing environment swaps testnet assets with no real value.

Swap the API key in the examples for your own production API key. Testing requires a separate testnet API key.

A quote request for an asset Chainflip has disabled:

curl --location 'https://chainflip-broker.io/quotes-native?apiKey=87517a91d5f34dbabfc1e410946a3a3c&sourceAsset=usdc.hub&destinationAsset=btc.btc&amount=100000000'
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.6.4",
"title": "Service Unavailable",
"status": 503,
"detail": "One of the assets in this swap is currently disabled on Chainflip",
"traceId": "00-6e04726aca44787669d57a48b1833007-ddd09a1fe1f24426-00",
"code": "asset_disabled"
}

A quote for an amount that is too large for the current liquidity:

{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "Bad Request",
"status": 400,
"detail": "There is currently no quote available for this amount, try a lower amount",
"traceId": "00-2f0c3d9b1a5e4c7d8e9f0a1b2c3d4e5f-1a2b3c4d5e6f7a8b-00",
"code": "insufficient_liquidity"
}