> ## 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](https://docs.flashnet.xyz/orchestra/security/attestation.md) 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](https://docs.flashnet.xyz/api/authentication.md) 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`, or exact-out or fixed delivery with a token named by address.
* `unsupported_delivery_mode`: fixed delivery with exact-out.
* `fixed_delivery_unsupported_route`: route does not support fixed delivery.
* `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.

## Tokens by address

A source or destination named by contract address or mint can also return these, all HTTP 400 except where noted. See [Any token](https://docs.flashnet.xyz/orchestra/any-token.md).

* `invalid_token_address`: the address is not valid for the chain's family.
* `token_not_found`: no token contract or mint at the address.
* `token_unsupported`: refused token, such as a Solana mint with a transfer fee or transfer hook.
* `token_blocked`: token on the Flashnet denylist.
* `insufficient_liquidity`: no route reaches or leaves the token.
* `route_unavailable`: the chain or your key is not enabled for that end.
* `invalid_request`: a quote with a source token omits `refundAddress`.
* `token_metadata_unavailable` (503): the token could not be read from the chain. Retry later.

## Quote calldata

* `calldata_unsupported_source` (400): `includeCalldata` requires an EVM source with known native or ERC-20 metadata. Omit the flag to use the usual deposit instructions.
* `calldata_unavailable` (502): the returned deposit instructions cannot be encoded as a plain transfer. Retry with the same key and body; do not fund partial instructions.

See [EVM funding transactions](https://docs.flashnet.xyz/orchestra/quotes.md#evm-funding-transactions).

## 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](https://docs.flashnet.xyz/api/rate-limits.md).
* `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](https://docs.flashnet.xyz/orchestra/status.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.