> ## 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.

# Errors

> Request and order failures

API errors normally return `{"error":{"code":"...","message":"..."}}`. This page covers common integration errors, not every endpoint-specific code. [Attestation](/orchestra/security/attestation) uses a separate response shape.

## Authentication

* `unauthorized`, `auth_required` (401): missing or invalid credentials.
* `forbidden` (403): key cannot access the endpoint or resource.
* `partner_disabled` (403): disabled account.
* `account_pending_approval`, `account_rejected` (403): account approval required when enforcement is enabled.
* `scope_required` (403): missing client scope.
* `origin_required`, `origin_not_allowed` (403): missing or disallowed browser origin.
* `read_token_required` (403): missing client read token.
* `invalid_read_token` (403): expired token or wrong key, order, or quote.
* `client_key_fee_fields_forbidden` (403): client request includes server-only fee fields.
* `turnstile_required`, `turnstile_failed` (403): missing or rejected browser verification, when enabled.

See [Authentication](/api/authentication) for token binding and endpoint restrictions.

## Idempotency

* `missing_idempotency_key` (400): missing `X-Idempotency-Key`.
* `invalid_idempotency_key` (400): key outside 1 to 255 printable ASCII characters.
* `idempotency_conflict` (409): same key, different body.
* `idempotency_in_progress` (409): original request still executing; wait for `Retry-After`.

## Request validation

* `invalid_request`, `validation_error` (400): invalid request fields.
* `invalid_query` (400): invalid query, such as status without exactly one selector.
* `invalid_address` (400): recipient or refund address invalid for its chain.
* `invalid_tx_hash` (400): invalid source-chain transaction hash.
* `ambiguous_query` (400): transaction hash matches multiple orders.
* `invalid_payout_destination`, `invalid_payout_address` (400): unsupported payout route or invalid address.
* `invalid_webhook_url` (400): rejected webhook URL.
* `not_found` (404): missing resource or different partner's resource.
* `payload_too_large` (413): body exceeds 1 MiB.
* `unsupported_media_type` (415): body is not JSON.

## Routing and amounts

These errors return HTTP 400:

* `unsupported_route`: destination outside the source's `route.to`.
* `unsupported_amount_mode`: exact-out route outside `exactOutTo`.
* `unsupported_delivery_mode`: fixed delivery with exact-out.
* `fixed_delivery_unavailable`: fixed delivery unavailable for route or partner.
* `unsupported_fee_plan`: route does not support fee settlement.
* `unsupported_asset`: USD exact-out target uses a non-USD-stablecoin destination.
* `invoice_required`: USD exact-out requires invoice billing.
* `amount_too_small`, `amount_too_large`: amount outside route bounds.
* `price_impact_too_high`: price impact exceeds the cap.
* `route_disabled`: route turned off.

## State

* `invalid_state` (400): action does not apply to current state.
* `conflict` (409): conflicting resource or offer decision.
* `expired` (409): ZeroConf offer expired.
* `quote_expired` (409): Lightning destination invoice expired.

## Rate and availability

* `rate_limited` (429): exhausted bucket. Follow `Retry-After` when present, otherwise `X-RateLimit-Reset`; see [Rate limits](/api/rate-limits).
* `internal_error` (500): server error.
* `flashnet_error` (502): upstream failure.
* `service_unavailable` (503): unavailable service.
* `spot_unavailable` (503): stale BTC/USD spot; USD amount requests cannot proceed.

## Standing deposit addresses

* `invalid_destination` (400): unsupported standing destination.
* `immutable_instruction` (400): PATCH changes fields other than `enabled`.
* `instruction_conflict` (409): existing reference has different instructions.
* `refund_not_available` (409): deposit or batch cannot be refunded.
* `standing_zeroconf_offer_conflict` (409): conflicting, expired, or ineligible offer decision.
* `standing_unavailable`, `scanner_unavailable` (503): standing service or scanner unavailable.

## Order errors

After creation, failures and refunds carry `error.code` on the order:

* `slippage_exceeded`: execution outside `slippageBps`.
* `exact_out_insufficient_input`: deposit below `requiredAmountIn`.
* `exact_out_input_above_max`: deposit above `maxAcceptedAmountIn`.
* `exact_out_target_not_met`: execution could not reach `targetAmountOut`.
* `duplicate_lightning_invoice`: invoice already used.
* `refund_address_missing`: no refund target; operator recovery required.

Screening can hold an order for review. Neither `awaiting_approval` nor a recovery event implies a partner-actionable ZeroConf offer; inspect the [order snapshot](/orchestra/status).