Find something... ⌘K

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.

CodeHTTPCauseWhat to do
invalid_input400A missing or malformed parameter or body: no addresses on a quote, a malformed txHash or orderId, an order not sent back unchangedFix the request; the message names the field
unsupported_chain400A chain Maxy does not swap onPick from GET /chains
unsupported_route400A pair Maxy does not swapPick from GET /pairs
wallet_mismatch400A signature that is not the wallet's the order namesSign with the wallet the quote names
verification_failed400The order's Bitcoin script or address does not match its intent, or a Solana transaction is not the deposit Maxy builtSend the order unchanged; change nothing but the signature
auth_required401No keySend x-maxy-key (a test key: POST /sandbox/keys)
invalid_api_key401A key Maxy did not issue, or a malformed oneCheck the key: mxk_live_ and 32 letters and digits
invalid_ticket401The stream ticket expired (they last 10 minutes), was changed, or is for another order or pairAsk a new one: POST /orders/{id}/stream-ticket or POST /prices/stream-ticket
key_revoked403The key was revoked (within about a minute)Use your new key
scope_denied403A publishable key asked for something only a secret key can doSend it from your server with the secret key
origin_not_allowed403The 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_refused403A test key (mxk_test_…) was sent to another Maxy function (a function on an older build answers 401 invalid_api_key). Nothing was doneTest keys work only on /functions/v1/maxy-api; the SDK does this for you
checkout_signature_invalid403The hosted checkout URL was changed after signing, its key was revoked, or its publishable key belongs to someone elseSign a new URL with signCheckoutUrl on your server
checkout_expired403The URL is past its expSign a new URL; links last an hour unless you ask for longer
not_found404No such route (the message suggests the right one), no order with that transaction, no webhook with that idCheck the path or id; a brand-new transaction may need a few seconds
quote_expired409The 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 expiredGet a new quote and sign again. Selling: do not pay
quote_mismatch409The escrow would lock more than the quote and its price band allow, or a Solana offer is more than 0.1% below the quoteGet a new quote
conflict409A 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_conflict409This Idempotency-Key was used within a day for a different requestUse a new key for a new order
order_state409Not allowed in the order's stateRead details.state and details.allowedStates; a committed order refunds at GET /orders/{id}/refund
amount_out_of_range422Below the smallest order (546 sats after costs)Raise the amount
order_cap_exceeded422Above your key's order size cap; quotes flag it in issues.orderCap. There is no other per-order maximumOrder less, or ask Maxy to raise the cap
insufficient_funds422The wallet holds less than the order needsFund the wallet
insufficient_liquidity422Maxy cannot fill this order now. No figure is givenA smaller amount, or later
tx_reverted422The transaction would revert (a Solana deposit is simulated before it is sent)Read the message
deposit_address_unverified422The escrow on chain does not match this orderDo not pay. Get a new quote
server_rejected422The solver or market maker refused the order; the message says whyRead the message. Selling: do not pay
rate_limited429Over 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 busyWait Retry-After seconds
internal_error500Something failed on Maxy's sideRetry; if it repeats, send Maxy the requestId
not_implemented501The server runs without that featureTell Maxy
service_unavailable503The key could not be checked just now. Nothing was doneRetry
timeout504A service behind the API did not answer in timeRetry; read the order first if it placed one
bad_response, http_error, network_error502A service Maxy depends on failed or answered something unusable. Nothing was signed or locked for youRetry when retryable is true; if it repeats, send Maxy the requestId
route_disabled503The 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).

CodeMeaningRetryableWhat was spentWhat to do
network_errorA host could not be reachedyesnothingRetry with backoff
timeoutNo answer in time, or a transaction not mined within the waityesin flight, for a sent transactionRetry a read; for a sent transaction, look it up before resending
http_errorHTTP 5xx or another unexpected status5xx: yesnothingRetry later
bad_responseA server answered something the SDK cannot use (missing fields, implausible price)oncenothingRetry once with fresh data (a new quote); report it if it repeats
rate_limitedHTTP 429yesnothingWait retryAfterSecondsOf(error) seconds when present, else back off
not_foundHTTP 404nonothingCheck the id
conflictThe state changed, or an idempotency key was reused with a different bodynonothingReload the order before acting
invalid_inputA parameter is missing or malformednonothingFix the call
config_missingA required configuration value is absentnonothingConfigure it
missing_dependencyA Solana order without @solana/web3.js installed (or passed as solanaWeb3 in a browser)nonothingnpm install @solana/web3.js
auth_requiredNo session, or the server rejected it (401, 403)nonothingSign in again
wallet_mismatchA signature came from another account, or the session belongs to another walletnonothingUse the same wallet throughout
wrong_chainThe wallet is on another chain and could not be switchednonothingSwitch the wallet
unsupported_chainThe chain has no deployment for this productnonothing
unsupported_routeNo route for this asset pair or tokennonothingUse another route (for example cross-evm first)
route_disabledThe route exists but is off right now (settler paused, token not allowlisted, vault paused, keeper not healthy, HTLC mint mode not deployed)laternothingTry later or another route
user_rejectedThe user rejected a wallet promptnonothing
signer_unsupportedThe signer cannot do what is needed (no message signing, wrong address type, unusable signature)nonothingUse another wallet
tx_revertedA simulation or a mined transaction revertednonothing for a simulation; gas for a mined revertRead message
verification_failedThe SDK refused data from a server or wallet that did not match its own computationnonothingDo not proceed; retry with fresh data; report it if it repeats
deposit_address_unverifiedA BTC to EVM payout is not escrowed in the settler for you, or a mint deposit is not registerednonothingDo not pay it
quote_expiredThe quote, deposit window or terms expirednonothingGet a new quote
quote_mismatchThe quote does not match the vault, market or terms asked fornonothingGet a new quote
insufficient_liquidityUnfillable right now: the order is larger than Maxy can fill at the moment (the message names no limit)laternothingTry a smaller amount
insufficient_fundsThe wallet's balance or Bitcoin coins do not cover the ordernonothingFund the wallet
amount_out_of_rangeOutside the product's limitsnonothingChange 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 answernonothingOrder less, or ask Maxy to raise the cap
key_revoked (HTTP 403, server_rejected)The API key was revokednonothingAsk Maxy for a new key
not_refundableNothing to refund yet, or at alllaternothingWait until unlocksAtOf(error), or check the order
abortedYour AbortSignal firednonothing further was sentStart again if you still want it
sandbox_refusedA test key asked for something with no sandbox form: a loan, a mint, sign-in or a low-level order buildernonothingUse swap.quote, createOrder, execute, getStatus and refund, or a live key
server_rejectedA server refused the request (4xx), or every Bitcoin node rejected a transactionnonothingRead 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.