unauthorized | 401 | All authenticated endpoints | Missing or invalid API key. |
auth_required | 401 | Deposit address resolution | Deposit address derivation requires an authenticated partner context. |
origin_required | 403 | All client-key endpoints | Client key in browser mode sent no Origin header. |
origin_not_allowed | 403 | All client-key endpoints | Origin header is not on the client key’s allowed list. |
scope_required | 403 | All client-key endpoints | The client key lacks the scope for this endpoint. |
read_token_required | 403 | /status, SSE | Client key read a shared resource without X-Read-Token / ?readToken=. |
invalid_read_token | 403 | /status, SSE | Read-token is malformed, expired, or not bound to this order and key. |
missing_idempotency_key | 400 | /quote, /submit, /onramp, /zeroconf/*, all mutating resource endpoints | X-Idempotency-Key header missing on a partner-authenticated mutating request. |
idempotency_conflict | 409 | /quote, /submit, /onramp, /zeroconf/*, all mutating resource endpoints | Same idempotency key reused with a different JSON body. |
idempotency_in_progress | 409 | /quote, /submit, /onramp, /zeroconf/*, all mutating resource endpoints | A request with the same idempotency key is still executing. Retry after it completes. |
unsupported_route | 400 | /estimate, /quote, /onramp | The (sourceChain, sourceAsset, destinationChain, destinationAsset) combination is not supported. |
unsupported_amount_mode | 400 | /quote, /onramp | amountMode is not supported for the selected route. /quote exact-out support includes stablecoin lightning:BTC sell routes, bitcoin:BTC -> (base|solana):USDC, and supported source routes to lightning:BTC. /onramp exact-out is not supported for direct BTC passthrough routes. |
unsupported_fee_plan | 400 | /estimate, /quote, /onramp | appFees or affiliateIds on a route with no supported fee settlement (for example pure-BTC routes with no stablecoin settlement leg), or fees on an amountFiatUsd exact-out onramp. |
unsupported_delivery_mode | 400 | /quote, /estimate, /onramp | deliveryMode=fixed combined with amountMode=exact_out, or requested on a route that does not support fixed delivery. |
fixed_delivery_unavailable | 400 | /quote, /estimate | Fixed delivery requested but not currently available for this partner or route. The message states the reason. |
unsupported_asset | 400 | /onramp | amountFiatUsd exact-out on a destination asset that is not a USD stablecoin. |
invoice_required | 400 | /onramp | amountFiatUsd with exact_out is limited to invoice-billing partners. |
spot_unavailable | 503 | /onramp, pay links | BTC/USD spot price is stale or unavailable, so amountFiatUsd cannot be converted. Retry later. |
invalid_request | 400 | /estimate, /quote, /submit, /onramp, /zeroconf/* | Request body failed business validation. Check field constraints. Stablecoin exact-out amounts must be whole-cent values. |
invalid_query | 400 | /status, /order, /history | Invalid query parameters. |
invalid_address | 400 | /quote, /onramp | Recipient or refund address is invalid for the target chain. |
invalid_state | 400 | /submit, /zeroconf/* | Endpoint was called in the wrong order state. For example, calling /zeroconf/accept on an order that is not awaiting_approval. |
invalid_payout_destination | 400 | PUT /v1/affiliates/:affiliateId | The (payoutChain, payoutAsset) combination is not in the live payout route table. |
conflict | 409 | /submit, /zeroconf/* | State changed concurrently. Retry the request. |
quote_expired | 409 | /submit | Destination invoice has expired (Lightning). Standard quote expiry does not return this error; expired quotes are always repriced at live market rates on submit. |
not_found | 404 | /status, /order, /submit, /zeroconf/* | Quote or order not found. |
amount_too_small | 400 | /estimate, /quote, /onramp | Swap input is below the Flashnet pool minimum. |
amount_too_large | 400 | /estimate, /quote, /onramp | Amount exceeds the maximum for the selected route. |
price_impact_too_high | 400 | /estimate, /quote, /onramp | Quote exceeds configured price impact constraints. |
rate_limited | 429 | /routes, /estimate, /quote, /order, /status | Too many requests. Back off and retry. See rate limits for per-endpoint thresholds. |
flashnet_error | 502 | /submit | Swap simulation or execution failed inside Flashnet. |
internal_error | 500 | Any | Unhandled server error. Some malformed JSON or schema violations surface as internal_error. Treat it as a request bug and retry only after fixing the payload. |
validation_error | 400 | Any | Request body or query parameters failed schema validation (Zod). |
expired | 409 | /zeroconf/accept, /zeroconf/decline | ZeroConf offer has expired. |
route_disabled | 400 | /estimate, /quote, /onramp | The selected route is temporarily disabled. |
service_unavailable | 503 | Any | Global kill switch is active. |
partner_disabled | 403 | All authenticated endpoints | Partner account is disabled. |
forbidden | 403 | /status, /order, /submit | Cross-partner access attempt. |
ambiguous_query | 400 | /status | Multiple orders match the provided txHash. Narrow the query. |
invalid_tx_hash | 400 | /submit | Transaction hash format is invalid for the source chain. |
payload_too_large | 413 | All JSON endpoints | Request body exceeds 1 MiB. |
unsupported_media_type | 415 | All JSON endpoints | Content type is not JSON on a JSON endpoint. |
