Orchestra returns errors in a standard envelope. For the envelope shape, see API Overview.Documentation Index
Fetch the complete documentation index at: https://docs.flashnet.xyz/llms.txt
Use this file to discover all available pages before exploring further.
What error codes can the API return?
| Code | HTTP | Endpoints | Description |
|---|---|---|---|
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, /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. |
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, /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, /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. |
/v1/orchestration/ prefix (e.g. /v1/orchestration/quote). Resource endpoints (/v1/affiliates/*, /v1/webhooks/*, /v1/accumulation-addresses/*, /v1/liquidation-addresses/*) are listed as “all mutating resource endpoints” where applicable.
Order-lifecycle error codes
These surface on order records (order.errorCode) and webhook payloads, not as HTTP responses. They indicate why an order moved to refunding or failed.
Order error messages are sanitized before they are stored or delivered publicly. Use errorCode for programmatic handling. errorMessage is partner-safe copy and does not include provider diagnostics, database errors, or stack details.
| Code | Terminal status | Description |
|---|---|---|
slippage_exceeded | refunding → refunded | Pool price moved past the quote’s slippageBps between deposit and execution. Order refunds automatically; no partner action required. |
exact_out_insufficient_input | refunding → refunded | The deposit was below requiredAmountIn for an exact-out strict order. |
exact_out_input_above_max | refunding → refunded | The deposit exceeded maxAcceptedAmountIn for an exact-out strict order. |
exact_out_target_not_met | refunding → refunded | The pool could not deliver targetAmountOut at execution time. |
duplicate_lightning_invoice | failed | A destination Lightning BOLT11 invoice was reused. Single-use invoices cannot settle twice. |
What are common error scenarios?
Submitting against an expired quote. Quotes expire after 2 minutes. If you callPOST /submit after the TTL, the engine reprices the order at live market rates and proceeds. Execution is still bounded by the quote’s slippageBps. If the pool has moved past that tolerance, the order refunds automatically with slippage_exceeded. The quote_expired HTTP error code applies only to expired Lightning destination invoices (BOLT11), not to general quote expiry.
Duplicate idempotency key with a different body. You reuse an X-Idempotency-Key value but change the request payload. The API returns 409 idempotency_conflict. Use a new key for each distinct request. Replaying the exact same request with the same key returns the stored response and sets X-Idempotency-Replayed: true.
Unsupported fee plan on a pure-BTC route. You request appFees or affiliateIds on a spark:BTC -> bitcoin:BTC quote. The API returns 400 unsupported_fee_plan. Fee plans require a stablecoin settlement leg. Routes between BTC endpoints with no stablecoin conversion do not support app fees.
Market moved against the quote. The deposit arrives and the pool has shifted past slippageBps. The order moves to refunding with errorCode=slippage_exceeded. No action is needed. The refund is automatic.
ZeroConf offer expired before response. You call POST /zeroconf/accept after the offer’s expiresAt has passed. The API returns 409 expired. The engine falls back to waiting for 1 on-chain confirmation automatically.