# Error Codes

## Details

When a request fails, the API answers with an [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) 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`.

```json
{
    "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](https://docs.chainflip-broker.io/features/ask-quote/) (`/quotes`, `/quotes-native`, and the deprecated `/quote`, `/quote-native`)
* [Starting a Swap](https://docs.chainflip-broker.io/features/start-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](https://docs.chainflip-broker.io/features/get-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

| `code` | HTTP status | Applies to | Meaning |
|---|---|---|---|
| `amount_below_minimum` | 400 | quote | The input amount does not cover the ingress fee. Try a bigger amount. |
| `egress_below_minimum` | 400 | quote | The output would be under the destination chain's minimum egress amount, usually because of high gas prices. Try a bigger amount. |
| `egress_fee_not_covered` | 400 | quote | The output would not cover the egress fee, usually because of high gas prices. Try a bigger amount. |
| `insufficient_liquidity` | 400 | quote | No 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_unavailable` | 400 | swap, vault payload | Chainflip'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_parameters` | 400 | swap, vault payload | Chainflip'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_parameters` | 400 | swap, vault payload | Chainflip'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_maintenance` | 503 | quote, swap, vault payload | Chainflip quoting is in maintenance mode. Retry later. |
| `swapping_maintenance` | 503 | quote, swap, vault payload | The Chainflip swap service is in maintenance mode. Retry later. |
| `deposit_channel_failed` | 503 | quote, swap, vault payload | The broker could not open a deposit channel. Retry later. |
| `too_many_channels` | 503 | quote, swap, vault payload | Chainflip's open channel cap has been hit. Retry later. |
| `asset_disabled` | 503 | quote, swap, vault payload | Chainflip 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_mode` | 503 | swap, vault payload | Chainflip'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_error` | 500 | quote, swap, vault payload | An upstream failure the API could not classify further. |
| `provider_unavailable` | 503 | quote | No healthy quote provider is available right now (for example every circuit breaker is open). Retry later. |
| `route_disabled` | 403 | quote | The pair is not enabled for your account. Enable it in your dashboard route configuration, or pick another pair. |
| `swap_unknown` | 404 | status | No 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_pending` | 404 | status | The 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](https://docs.chainflip-broker.io/environments/testing/) environment swaps testnet assets with no real value.
>
> Swap the API key in the examples for your own [production API key](https://chainflip-broker.io/register). Testing requires a separate [testnet API key](https://perseverance.chainflip-broker.io/register).

A quote request for an asset Chainflip has disabled:

```bash
curl --location 'https://chainflip-broker.io/quotes-native?apiKey=87517a91d5f34dbabfc1e410946a3a3c&sourceAsset=usdc.hub&destinationAsset=btc.btc&amount=100000000'
```

```json
{
    "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:

```json
{
    "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"
}
```
