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

---
Source: https://maxy.co/docs/error-codes (Maxy Docs › Reference › HTTP API)
