> ## 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. # Error codes > Complete reference of Orchestra API error codes, HTTP statuses, affected endpoints, and common error scenarios. Orchestra returns errors in a standard envelope. For the envelope shape, see [API Overview](/products/orchestration/api/overview#errors). ## 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. `/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`, `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. 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](/products/orchestration/api/overview#rate-limiting) 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. | Endpoint paths are abbreviated. Full paths use the `/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 call `POST /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.