Skip to main content
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

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.
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 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

Codes for signed requests

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

Swap codes

Submission codes

Batch order codes

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, and the batch order routes that need the network answer NETWORK_NOT_ACTIVE where batch orders are not active.

Redemption codes

Redemptions also use the codes for signed requests. A failed redemption’s failure.code uses some of the same names; Lifecycle 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.

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.

Rate limits

Allowances, rate-limit headers, and how to back off.

Retries and idempotency

Which requests are safe to repeat.