Skip to main content
API errors normally return {"error":{"code":"...","message":"..."}}. This page covers common integration errors, not every endpoint-specific code. 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 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.
  • 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.