unauthorized | 401 | All authenticated endpoints | Missing or invalid API key. |
auth_required | 401 | Deposit address resolution | Deposit address derivation requires an authenticated partner context. |
missing_idempotency_key | 400 | /quote, /submit, /onramp, /reprice/*, /zeroconf/*, all mutating resource endpoints | X-Idempotency-Key header missing on a partner-authenticated mutating request. |
idempotency_conflict | 409 | /quote, /submit, /onramp, /reprice/*, /zeroconf/*, all mutating resource endpoints | Same idempotency key reused with a different JSON body. |
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. exact_out is limited to bitcoin:BTC -> (base|solana):USDC and any source -> lightning:BTC. |
unsupported_fee_plan | 400 | /estimate, /quote, /onramp | appFees, affiliateId, or affiliateIds is not supported for the selected route or quote mode. Returned for pure-BTC routes with no stablecoin settlement leg. |
invalid_request | 400 | /estimate, /quote, /submit, /onramp, /reprice/*, /zeroconf/* | Request body failed business validation. Check field constraints. |
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, /reprice/*, /zeroconf/* | Endpoint was called in the wrong order state. For example, calling /reprice/approve 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, /reprice/*, /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 repriced at live market rates on submit. |
not_found | 404 | /status, /order, /submit, /reprice/*, /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, /reprice/approve | 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. |
