Reference / HTTP API
Error codes
Look up any error. Every error from the HTTP API is { "error": { "code", "message", "details"?, "retryable", "docs" }, "requestId" }, with the same id in the x-request-id header. Branch on code, retry when retryable is true, and quote requestId to Maxy. docs links the code's own row below.
| Code | HTTP | Cause | What to do |
|---|---|---|---|
invalid_input | 400 | A missing or malformed parameter or body: no addresses on a quote, a malformed txHash or orderId, an order not sent back unchanged | Fix the request; the message names the field |
unsupported_chain | 400 | A chain Maxy does not swap on | Pick from GET /chains |
unsupported_route | 400 | A pair Maxy does not swap | Pick from GET /pairs |
wallet_mismatch | 400 | A signature that is not the wallet's the order names | Sign with the wallet the quote names |
verification_failed | 400 | The order's Bitcoin script or address does not match its intent, or a Solana transaction is not the deposit Maxy built | Send the order unchanged; change nothing but the signature |
auth_required | 401 | No key | Send x-maxy-key (a test key: POST /sandbox/keys) |
invalid_api_key | 401 | A key Maxy did not issue, or a malformed one | Check the key: mxk_live_ and 32 letters and digits |
invalid_ticket | 401 | The stream ticket expired (they last 10 minutes), was changed, or is for another order or pair | Ask a new one: POST /orders/{id}/stream-ticket or POST /prices/stream-ticket |
key_revoked | 403 | The key was revoked (within about a minute) | Use your new key |
scope_denied | 403 | A publishable key asked for something only a secret key can do | Send it from your server with the secret key |
origin_not_allowed | 403 | The page's origin is not on the key's list, or the call has no origin (a server) | Ask Maxy to add the origin; from a server, use the secret key |
sandbox_key_refused | 403 | A test key (mxk_test_…) was sent to another Maxy function (a function on an older build answers 401 invalid_api_key). Nothing was done | Test keys work only on /functions/v1/maxy-api; the SDK does this for you |
checkout_signature_invalid | 403 | The hosted checkout URL was changed after signing, its key was revoked, or its publishable key belongs to someone else | Sign a new URL with signCheckoutUrl on your server |
checkout_expired | 403 | The URL is past its exp | Sign a new URL; links last an hour unless you ask for longer |
not_found | 404 | No such route (the message suggests the right one), no order with that transaction, no webhook with that id | Check the path or id; a brand-new transaction may need a few seconds |
quote_expired | 409 | The quote is older than 60 seconds, or the intent's deadline (2 hours) passed; selling, the commit deadline or the deposit window passed; on Solana, the signed request or the deposit's blockhash expired | Get a new quote and sign again. Selling: do not pay |
quote_mismatch | 409 | The escrow would lock more than the quote and its price band allow, or a Solana offer is more than 0.1% below the quote | Get a new quote |
conflict | 409 | A sixth webhook endpoint (5 per key); the solver could not lock the payout; the sell is already paid out; the Solana offer is no longer open, or not in the state this stage needs (broadcast before PaymentLocked) | Delete an endpoint; otherwise get a new quote, and do not pay |
idempotency_conflict | 409 | This Idempotency-Key was used within a day for a different request | Use a new key for a new order |
order_state | 409 | Not allowed in the order's state | Read details.state and details.allowedStates; a committed order refunds at GET /orders/{id}/refund |
amount_out_of_range | 422 | Below the smallest order (546 sats after costs) | Raise the amount |
order_cap_exceeded | 422 | Above your key's order size cap; quotes flag it in issues.orderCap. There is no other per-order maximum | Order less, or ask Maxy to raise the cap |
insufficient_funds | 422 | The wallet holds less than the order needs | Fund the wallet |
insufficient_liquidity | 422 | Maxy cannot fill this order now. No figure is given | A smaller amount, or later |
tx_reverted | 422 | The transaction would revert (a Solana deposit is simulated before it is sent) | Read the message |
deposit_address_unverified | 422 | The escrow on chain does not match this order | Do not pay. Get a new quote |
server_rejected | 422 | The solver or market maker refused the order; the message says why | Read the message. Selling: do not pay |
rate_limited | 429 | Over 600 calls a minute per key (120 per IP on the routes that take no key); selling, the wallet already has three unpaid sell orders open or the solver is busy | Wait Retry-After seconds |
internal_error | 500 | Something failed on Maxy's side | Retry; if it repeats, send Maxy the requestId |
not_implemented | 501 | The server runs without that feature | Tell Maxy |
service_unavailable | 503 | The key could not be checked just now. Nothing was done | Retry |
timeout | 504 | A service behind the API did not answer in time | Retry; read the order first if it placed one |
bad_response, http_error, network_error | 502 | A service Maxy depends on failed or answered something unusable. Nothing was signed or locked for you | Retry when retryable is true; if it repeats, send Maxy the requestId |
route_disabled | 503 | The route is off right now (a paused settler, a token not allowed) | Another route, or later |
SDK codes
The SDK raises a MaxyError subclass with the same code in error.code, and the same link in docsUrl. "What was spent" says what may already have happened when it is thrown: nothing; gas (a transaction was sent and may have cost gas); or in flight (funds may have moved; check on chain before acting).
| Code | Meaning | Retryable | What was spent | What to do |
|---|---|---|---|---|
network_error | A host could not be reached | yes | nothing | Retry with backoff |
timeout | No answer in time, or a transaction not mined within the wait | yes | in flight, for a sent transaction | Retry a read; for a sent transaction, look it up before resending |
http_error | HTTP 5xx or another unexpected status | 5xx: yes | nothing | Retry later |
bad_response | A server answered something the SDK cannot use (missing fields, implausible price) | once | nothing | Retry once with fresh data (a new quote); report it if it repeats |
rate_limited | HTTP 429 | yes | nothing | Wait retryAfterSecondsOf(error) seconds when present, else back off |
not_found | HTTP 404 | no | nothing | Check the id |
conflict | The state changed, or an idempotency key was reused with a different body | no | nothing | Reload the order before acting |
invalid_input | A parameter is missing or malformed | no | nothing | Fix the call |
config_missing | A required configuration value is absent | no | nothing | Configure it |
missing_dependency | A Solana order without @solana/web3.js installed (or passed as solanaWeb3 in a browser) | no | nothing | npm install @solana/web3.js |
auth_required | No session, or the server rejected it (401, 403) | no | nothing | Sign in again |
wallet_mismatch | A signature came from another account, or the session belongs to another wallet | no | nothing | Use the same wallet throughout |
wrong_chain | The wallet is on another chain and could not be switched | no | nothing | Switch the wallet |
unsupported_chain | The chain has no deployment for this product | no | nothing | |
unsupported_route | No route for this asset pair or token | no | nothing | Use another route (for example cross-evm first) |
route_disabled | The route exists but is off right now (settler paused, token not allowlisted, vault paused, keeper not healthy, HTLC mint mode not deployed) | later | nothing | Try later or another route |
user_rejected | The user rejected a wallet prompt | no | nothing | |
signer_unsupported | The signer cannot do what is needed (no message signing, wrong address type, unusable signature) | no | nothing | Use another wallet |
tx_reverted | A simulation or a mined transaction reverted | no | nothing for a simulation; gas for a mined revert | Read message |
verification_failed | The SDK refused data from a server or wallet that did not match its own computation | no | nothing | Do not proceed; retry with fresh data; report it if it repeats |
deposit_address_unverified | A BTC to EVM payout is not escrowed in the settler for you, or a mint deposit is not registered | no | nothing | Do not pay it |
quote_expired | The quote, deposit window or terms expired | no | nothing | Get a new quote |
quote_mismatch | The quote does not match the vault, market or terms asked for | no | nothing | Get a new quote |
insufficient_liquidity | Unfillable right now: the order is larger than Maxy can fill at the moment (the message names no limit) | later | nothing | Try a smaller amount |
insufficient_funds | The wallet's balance or Bitcoin coins do not cover the order | no | nothing | Fund the wallet |
amount_out_of_range | Outside the product's limits | no | nothing | Change the amount |
order_cap_exceeded | "Order size is capped for this API key. Try $100 or less.": the order is above your key's order size cap; prices and quotes still answer | no | nothing | Order less, or ask Maxy to raise the cap |
key_revoked (HTTP 403, server_rejected) | The API key was revoked | no | nothing | Ask Maxy for a new key |
not_refundable | Nothing to refund yet, or at all | later | nothing | Wait until unlocksAtOf(error), or check the order |
aborted | Your AbortSignal fired | no | nothing further was sent | Start again if you still want it |
sandbox_refused | A test key asked for something with no sandbox form: a loan, a mint, sign-in or a low-level order builder | no | nothing | Use swap.quote, createOrder, execute, getStatus and refund, or a live key |
server_rejected | A server refused the request (4xx), or every Bitcoin node rejected a transaction | no | nothing | Read message and serverCode |
Two outcomes are returned rather than thrown, because they are not failures: a Bitcoin broadcast with outcome.status === 'ambiguous' (no node confirmed it; the payment may be in flight; never pay again before looking the txid up), and a swap getStatus 404, which is reported as pending.