> ## Documentation Index
> Fetch the complete documentation index at: https://docs.multiliquid.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error body, every error code, and what to do about each.

Every error has the same JSON body. Handle it by its `code`, read `details` for what to change, and quote `requestId` to support.

## Error body

```json theme={null}
{
  "error": "unknown query parameter `foo`; expected `network` or `inputToken`",
  "status": 400,
  "code": "INVALID_REQUEST",
  "details": { "location": "query", "field": "foo" },
  "requestId": "req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f"
}
```

| Field | Description |
| - | - |
| `error` | A human-readable message. When a query parameter or JSON body field is rejected, the message names it. [Handling errors by code](#handling-errors-by-code) explains when you can rely on the wording. |
| `status` | The HTTP status, repeated. |
| `code` | The machine-readable reason. Every error has one. |
| `details` | Optional. An object whose properties depend on `code`, as the [catalogue](#error-codes) lists. A code can gain properties over time, so ignore properties you don't use. |
| `requestId` | The server-generated ID of this HTTP request. The same ID is in the response's `X-Request-Id` header. It is unrelated to a redemption's `redemptionId`. |

## Handling errors by code

Key your handling on `code`, not on the HTTP status. One code can arrive with different statuses: `UNSUPPORTED_TOKEN` is a `400` for a quote's query and a `422` for a build's body. One status also covers many codes.

* **Messages** are written for people, for logs and support tickets, and their wording can change. Don't match them, unless a condition has only a generic code.
* **Amounts** in `details` and in messages, such as `required`, `available`, `bound`, and `quoted`, are whole tokens as decimal strings, as everywhere in the API: `"995.21"` is 995.21 \$TSY. **Addresses**, such as `token` and `spender`, are lowercase `0x` hex on EVM and base58 on Solana.
* **New properties** can appear in `details` over time. Ignore the ones you don't use.

## Request IDs

Every response, successful or not, carries an `X-Request-Id` header: `req_` followed by 32 hexadecimal digits. Error bodies repeat it as `requestId`. Multiliquid generates the ID for each request and ignores any `X-Request-Id` you send. This `req_` ID identifies the HTTP request and is unrelated to a redemption's `redemptionId`.

```http theme={null}
HTTP/2 200
content-type: application/json
x-request-id: req_019a5c1e8f3b7c2d9e4f6a1b2c3d4e5f
```

> [!TIP]
>
> A support request that quotes the `requestId` lets Multiliquid find that exact request in its logs. Recording the header for every call, not only failed ones, makes any later question about a request easy to answer.

## Headers on error responses

* Every `429` carries `Retry-After`, the whole seconds to wait, and `details.retryAfterSeconds` repeats it. So does a `503` with the message `service is busy; retry later`, which you can retry after `Retry-After`. [Rate limits](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md) explains how to back off.
* A `401` carries `WWW-Authenticate: Bearer`.
* A `405` carries `Allow`, listing the methods the route supports.
* An error response to a counted request, a `408` included, also carries the `RateLimit-*` headers.

## Error codes

### General codes

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `INVALID_REQUEST` | 400 | A malformed request: unparseable JSON, a missing JSON content type, or an invalid, missing, or unknown query or path parameter, including a cursor sent to another listing than the one it was issued for. Every route in the OpenAPI document rejects an unknown query parameter, a route that takes a JSON body included; a parameter that usually carries a credential, such as `api_key` or `token`, gets a pointer to the `Authorization` header instead. `details`: `field` when one parameter or field is at fault, and `location` (`query`, `path`, or `body`) when the place of the rejected value is known. A rejection that cannot name the value at fault, such as a value the service cannot store, has no `details`. | Correct the request. Resending it unchanged fails again. |
| `INVALID_BODY` | 422 | A well-formed JSON body fails validation: an unknown, missing, or mistyped field, or a value the operation rejects, such as an amount sent as a JSON number or with more than 6 decimal places. `details`: `location` (`body`) and, when known, `field`, a dotted path such as `inputs[0].routeId`. | Correct the body. |
| `UNAUTHORIZED` | 401 | The credential is missing, invalid, expired, or revoked. | Send a valid credential. |
| `FORBIDDEN` | 403 | The credential has no access to the resource or feature, for example a member's credential on an admin-only operation. | Don't retry without new access. |
| `INSUFFICIENT_SCOPE` | 403 | The API key is valid but lacks the operation's scope. `details`: `requiredScope`, one of `read`, `trade`, `cp:operate`, or `cp:admin`. | Use a key with the scope; an organization admin can create one, as [Authentication](https://docs.multiliquid.xyz/api-reference/authentication.md#scopes) explains. |
| `ORGANIZATION_NOT_SELECTED` | 403 | An account session that selects no organization, on any route it is sent to, public routes included. | Select an organization in the Multiliquid app, or use an API key, which always belongs to one. |
| `NOT_FOUND` | 404 | No route matches the path, or the resource does not exist for the caller. | Check the path and identifiers. |
| `METHOD_NOT_ALLOWED` | 405 | The route does not support the method. | Use a method that the `Allow` header lists. |
| `CONFLICT` | 409 | The request conflicts with the resource's current state, and no specific code applies. | Read the current state before retrying. |
| `PAYLOAD_TOO_LARGE` | 413 | The body exceeds the route's limit, or the route accepts no body. `details`: `limitBytes`, which is `0` for a route without a body. | Send a body within the limit. |
| `REQUEST_TIMEOUT` | 408 | The request exceeded the 30-second request deadline. | Read the state before retrying a request that changes it, because it may have taken effect. |
| `RATE_LIMITED` | 429 | A request allowance is spent, or the service is busy. On a [counted route](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md#counted-routes), `RateLimit-Remaining` is `0` for a spent allowance and above `0` for a busy service. `details`: `retryAfterSeconds`. | Retry after `Retry-After`. |
| `SERVICE_UNAVAILABLE` | 503 | A dependency is unavailable, the service is busy or paused, or the feature is not active on this deployment. `details`: `retryAfterSeconds` when the service is busy. | Retry later, after `Retry-After` when present. |
| `NETWORK_NOT_ACTIVE` | 503 | The API does not serve the network for the route: a quote, build, pair listing, or new submission on a network that `GET /v1/networks` lists with `active: false`, or a batch order route where batch orders are not active on the network: preparation and order intake, and on Solana also discovery (`GET /v1/batch-orders/info` and `GET /v1/batch-orders/capital-providers`) and nonce account registration, or a delegate admin route on a network where delegate administration is not active. `details`: `network`. | Don't send the request again, which fails the same way; use an active network. |
| `INTERNAL_ERROR` | 500 | An unexpected server failure. | Retry later, and quote `requestId` to support if it persists. |

### Codes for signed requests

Batch orders and redemptions share these codes, with the same `details`.

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `INVALID_SIGNATURE` | 422 | The signature does not authorize the signed user: it signs other data, is malformed, or the user's contract wallet rejects it. | Sign again. |
| `NO_QUOTE` | 422 | The amounts cannot be quoted, or the quote does not honor a signed exact amount. A batch order or redemption preparation names its capital provider in `details.providers`, with the decoded `error` (`name` and `message`), as a swap quote does. A signed batch order or redemption gives no `details`. | Change the amounts, or quote and sign again. |
| `BOUND_NOT_MET` | 422 | The quote already violates a signed bound. `details`: `field` (`minAmountOut` or `maxAmountIn`), the `bound`, the `quoted` amount, and the `legIndex` of the leg. | Quote again and sign the new amounts. |
| `INSUFFICIENT_BALANCE` | 422 | The user's token balance is below what the signed request needs. `details`: `token`, `required`, and `available`, in whole tokens. | Fund the wallet, then submit the same signed request again. |
| `INSUFFICIENT_ALLOWANCE` | 422 | The user's token allowance is below what the signed request needs. `details`: `token`, `spender` (the contract to approve), `required`, and `available`, in whole tokens. | Approve at least `required` to `spender`, then submit the same signed request again. |
| `UNSUPPORTED_ROUTE` | 422 | A batch order names a route, asset, or pair that batch orders do not support on the network, such as a swap between two stablecoins or a Solana capital provider with Treasury enabled, or a redemption names a route other than `6` or `7`, with `details.field` naming the route field. | Sign again with one that discovery or configuration lists. |
| `OPERATOR_MISMATCH` | 409 | The signed operator is not the one the operation requires: the capital provider's current operator for a batch order, or the redemption operator for a redemption. `details`: `expected`, the operator to sign for, `null` when there is none. | Sign again with `details.expected` as the operator; when it is `null`, choose another capital provider. |

### Swap codes

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `UNSUPPORTED_TOKEN` | 400 for a query, 422 for a body | A swap token, or an Ethereum batch order's token, is not listed on the network. `details`: `field` (`inputToken` or `outputToken`), `token`, and `network`. | Choose a token that [discovery](https://docs.multiliquid.xyz/api-reference/swap/discovery.md) lists. |
| `UNSUPPORTED_PAIR` | 400 for a query, 422 for a body | No listed capital provider swaps the token pair, or the pair does not list the capital provider the request names. For batch orders, a capital provider takes only its own stablecoin and the RWAs it whitelists on Ethereum, and only its own pairs on Solana, and an order that names one token for both sides is also rejected with this code. `details`: `inputToken`, `outputToken`, `network`, and the requested `capitalProvider`, if any. | Choose a pair that discovery lists, or another capital provider. |
| `UNKNOWN_CAPITAL_PROVIDER` | 400 for a query, 422 for a body | The requested `capitalProvider` is not listed on the network, or for a batch order preparation takes no batch orders there. `details`: `field`, the `capitalProvider` sent, and `network`. | Omit `capitalProvider` or name a listed capital provider. |
| `NO_QUOTE` | 400 for a query, 422 for a body | Every capital provider the pair lists, or the one the request names, rejected the quote, including one whose custody cannot pay out the swap (`ERC20InsufficientBalance` or `ERC20InsufficientAllowance`), \$TSY in above the user's Treasury credits, none included (`InsufficientCredits`), \$TSY that cannot be priced now (`CreditsUnavailable`), and an amount whose quote rounds to zero (`ZeroAmount`). `details.providers`: each `capitalProvider` and the decoded `error` (`name` and `message`) it rejected the quote with. | Change the amount or capital provider, or retry later. |
| `BOUND_NOT_MET` | 422 | The build's quote already violates its explicit bound. `details`: `field` (`minAmountOut` or `maxAmountIn`), the `bound` sent, and the `quoted` amount. | Quote again, or loosen the bound. |
| `UNSUPPORTED_FIELD` | 422 | A field applies only to another runtime, such as `receiver` on Solana. `details`: `field` and `network`. | Remove the field. |

### Submission codes

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `INVALID_TRANSACTION` | 422 | The submitted or decoded transaction cannot be decoded, is of an unsupported type, is for another chain, creates a contract, has an invalid signature, or exceeds its size limit; a submitted Solana transaction's blockhash has expired; or the submitted transactions do not share one sender with consecutive nonces (EVM) or one fee payer (Solana), or a Solana transaction repeats the one before it. `details` on a submission: `location` (`body`) and `field`, the transaction, such as `signedTransactions[1]`. | Build and sign the transaction again. |
| `UNSUPPORTED_TRANSACTION` | 422 | The submitted transaction neither calls the swap contract or a listed stablecoin delegate (on Solana, the swap or Treasury program) nor approves one, or sends ETH; or two submitted transactions are not a build's approval (EVM) or account creation (Solana) followed by its swap. `details`: `location` (`body`) and `field`, the transaction, such as `signedTransactions[1]`. | Submit only the transactions a build returns, in signing order, or a preparation's `approval` alone. |
| `NONCE_ALREADY_USED` | 409 | The sender's account nonce is already past the EVM transaction's nonce, as when the wallet sent another transaction after the build or preparation. | Build or prepare again, and sign the new transaction as returned. |
| `SIMULATION_FAILED` | 422 | The transaction fails in simulation; the message names the decoded revert or program error. A queued submission that fails in simulation when its turn comes reports it as its `error.code`. | Fix the cause, then build and sign again. |
| `TRANSACTION_REJECTED` | 422 | The network's node refused the transaction. A queued submission that the node refuses when its turn comes reports it as its `error.code`. | Build and sign the transaction again. |

### Batch order codes

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `DUPLICATE_ORDER` | 409 | An accepted order already uses the order's nonce, or on Solana its signed transaction; an order is never accepted twice. `details`: `orderId`, the accepted order. | Read the order with `GET /v1/batch-orders/{orderId}`. To place another order, prepare and sign a new one. |
| `NONCE_ALREADY_USED` | 409 | The swap contract already used the order's nonce, and no accepted order holds it. | Sign again with a new nonce. |
| `OPERATOR_NOT_SELECTED` | 409 | The capital provider has not selected an operator, so it takes no batch orders. | Choose another capital provider or try later. |
| `BATCH_ORDERS_DISABLED` | 409 | Batch orders are turned off for the capital provider, which takes no new orders or capacity. | Choose another capital provider. |
| `INTAKE_CLOSED` | 409 | The batch takes no new orders or capacity now: intake closes at the 4:30 PM New York cut-off and reopens at the 5:00 PM release. `details` on an order: `cutoffAt`, the cut-off that passed, and `opensAt`, when intake opens again. | Submit after `opensAt`, signed for the new batch's deadline window. |
| `INSUFFICIENT_CAPACITY` | 409 | The capital provider's posted capacity cannot cover the order. `details`: `token`, the pool that falls short, and `required` and `available`. Preparation reports the same comparison in `checks.capacity`. | Lower the amount or choose another capital provider. |
| `CAPACITY_BELOW_RESERVED` | 409 | A capacity update would set the posted total below what accepted orders reserve. `details`: `reserved`. | Post at least `reserved`. |
| `CUSTODY_NOT_WHITELISTED` | 409 | The capital provider's custody cannot send the RWA, or the RWA has no whitelist adapter, so the capital provider cannot post nonzero mainnet capacity for it. | Have the custody whitelisted with the RWA's issuer, then post again. |
| `DEADLINE_OUT_OF_WINDOW` | 422 | The signed deadline is outside the batch's deadline window. `details`: `earliest` and `latest`, the first and last valid deadlines in Unix seconds. | Sign again with a deadline in the window. |
| `SWAP_PAUSED` | 422 | The swap contract is paused. | Try again later. |
| `ACCOUNT_BLACKLISTED` | 422 | A signed account is blacklisted. `details`: `role`, which is `user`, `operator`, or `receiver`. | Use another account. |
| `DELEGATE_NOT_SWAPPABLE` | 422 | The capital provider's delegate is paused or not fully configured on-chain. | Choose another capital provider. |
| `RWA_NOT_WHITELISTED` | 422 | The capital provider does not whitelist an RWA that the order swaps. `details`: `token`. | Choose another capital provider or RWA. |
| `RECEIVER_NOT_ELIGIBLE` | 422 | The output RWA's whitelist refuses the receiver. | Sign again with an eligible receiver. |
| `RISK_LIMIT_EXCEEDED` | 422 | An RWA risk control refuses the swap, for example a daily volume limit. | Lower the amount or try again later. |
| `CANCELLATION_CLOSED` | 409 | The order's cancellation window closed at its batch's 4:30 PM New York cut-off. | Don't retry; the order stays in its batch. |
| `CANCELLATION_EXPIRED` | 422 | The cancellation's `expiresAt` has passed. | Prepare and sign a new cancellation. |
| `REPORTING_CLOSED` | 409 | The order takes no report now: reports open at its batch's 5:00 PM New York release and close at 5:30 PM. | Report within the window. |
| `NONCE_ACCOUNT_UNAVAILABLE` | 409 | The capital provider's operator has no free Solana nonce account. | Try again later or choose another capital provider. |
| `TOKEN_ACCOUNT_MISSING` | 422 | A Solana order needs the user's associated token accounts of both tokens, and one does not exist. `details`: `token`, the mint; `account`, the missing account's address; and `tokenProgram`, the address of the mint's token program (SPL Token or Token-2022). | Create the account, for example with the associated token account program's idempotent create instruction, then prepare the order again. |
| `PREPARED_ORDER_STALE` | 409 | A prepared Solana order no longer matches current state: its nonce account was taken or advanced, the signed transaction differs from the one the order's terms now build, or the transaction limits or fee bounds changed. | Prepare and sign again. |

A Solana order also uses `INVALID_TRANSACTION` for a transaction that cannot be decoded and `SIMULATION_FAILED` when its run at admission fails. Batch orders also use `OPERATOR_MISMATCH` and the other [codes for signed requests](#codes-for-signed-requests), and the batch order routes that need the network answer `NETWORK_NOT_ACTIVE` where batch orders are not active.

### Redemption codes

| Code | Status | Meaning | What to do |
| - | - | - | - |
| `DEADLINE_TOO_SOON` | 422 | A redemption deadline, signed or requested in a preparation, is not more than ten minutes away. `details`: `minimumDeadline` (Unix seconds, a decimal string) and `minimumLifetimeSeconds`. | Prepare again with a later deadline, then sign. |
| `UNSUPPORTED_ASSET` | 422 | A signed redemption asset ID or delegate ID is not the one redemptions accept. `details`: `field` and `expected`. | Sign again with `details.expected` in `details.field`. |
| `NONCE_MISMATCH` | 422 | The signed nonce is not the user's current nonce. `details`: `signedNonce` and `currentNonce`. | Prepare and sign again. |
| `INSUFFICIENT_CREDITS` | 422 | The user's Treasury credits are below the \$TSY the redemption needs. `details`: `token` (\$TSY), `required`, and `available`, in whole \$TSY. | Prepare and sign again for less: the credits cover at most `available`. |
| `INSUFFICIENT_LIQUIDITY` | 422 | Not enough USDC is available to settle the redemption now. `details`: `token` (USDC); `required`, the quoted USDC output plus, for exact \$TSY in, an execution reserve of 1 basis point of it, and `available`, the most USDC Multiliquid can pay out now, as preparation's [`checks.liquidity`](https://docs.multiliquid.xyz/api-reference/treasury/prepare-and-sign#checks) reports it, both in whole USDC. | Prepare and sign again so that `required` is within `available`, or retry later. |
| `NONCE_IN_USE` | 409 | Another redemption holds the user's nonce and may still settle. `details`: `redemptionId`, when known. | Track that redemption instead of signing again. |

Redemptions also use the [codes for signed requests](#codes-for-signed-requests). A failed redemption's `failure.code` uses some of the same names; [Lifecycle](https://docs.multiliquid.xyz/api-reference/treasury/lifecycle.md#failure-codes) lists them.

### Codes from the Multiliquid app

The OpenAPI document's list of codes also holds five that only the Multiliquid app's delegate routes (deployment, naming, and batch order enablement) return. No route in these docs returns them.

| Code | Status | Meaning |
| - | - | - |
| `DELEGATE_LIMIT_REACHED` | 409 | The organization has reached its delegate limit on the network. |
| `DELEGATE_DEPLOYMENT_DISABLED` | 422 | Delegate deployment is not enabled for the network. |
| `DELEGATE_DEPLOYMENT_INCOMPLETE` | 409 | The delegate's deployment has not completed, so it cannot be named or have batch orders turned on yet. |
| `GAS_PRICE_TOO_HIGH` | 503 | The network's gas price is above the deployment maximum. |
| `DELEGATE_DEPLOYER_UNFUNDED` | 503 | The deployment wallet cannot pay for a deployment now. |

## Responses without this body

A response that the load balancer or HTTP server sends before the request reaches the API, such as a load balancer `502` or `504`, or a `431` for oversized headers, has neither this body nor an `X-Request-Id` header. Check that an error response is JSON before reading `code`.

## Related

> [card] [Rate limits](https://docs.multiliquid.xyz/api-reference/guides/rate-limits.md)
>
> Allowances, rate-limit headers, and how to back off.

> [card] [Retries and idempotency](https://docs.multiliquid.xyz/api-reference/guides/idempotency.md)
>
> Which requests are safe to repeat.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.