> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}.
> Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts.
> Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md.
> Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md.
> Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers.
> Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews.
> Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming.
> Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md.
> Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors.
> API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product.
> Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes.
> When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records.
> Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md.

# Facilitator Service API errors

> Reasons returned by the Facilitator Service API when a request fails.

For error response shapes and general errors that can be returned by any Circle
API, see [API errors](/api-reference/errors).

## Verify and settle reasons

These reason strings appear in
[`/verify`](/api-reference/facilitator-service/verify-payment) responses as
`invalidReason` and in
[`/settle`](/api-reference/facilitator-service/settle-payment) responses as
`errorReason`.

| Reason | Cause |
| - | - |
| `eip2612_asset_mismatch` | The permit `asset` doesn't equal `permitted.token` |
| `eip2612_deadline_expired` | The permit `deadline` is less than 10 seconds away |
| `eip2612_from_mismatch` | The permit `from` doesn't equal `permit2Authorization.from` |
| `eip2612_spender_not_permit2` | The permit `spender` isn't Permit2 |
| `insufficient_funds` | The buyer's USDC balance is too low |
| `invalid_eip2612_extension_format` | The permit extension is partly filled, malformed, or its signature isn't 65 bytes |
| `invalid_exact_evm_payload_authorization_valid_after` | `validAfter` is in the future: the authorization is not yet valid |
| `invalid_exact_evm_payload_authorization_valid_before` | `validBefore` has passed: the authorization has expired |
| `invalid_exact_evm_payload_authorization_value_mismatch` | The signed `value` doesn't equal `paymentRequirements.amount` |
| `invalid_exact_evm_payload_recipient_mismatch` | The authorization `to` doesn't equal `payTo` |
| `invalid_exact_evm_payload_signature` | The signature doesn't match `from` |
| `invalid_network` | The `network` isn't supported or doesn't match the asset |
| `invalid_payload` | The `paymentPayload` is malformed or missing required fields |
| `invalid_payment_requirements` | `paymentRequirements` differs from `accepted`, including the amount on `/verify` |
| `invalid_permit2_recipient_mismatch` | `witness.to` doesn't equal `payTo` |
| `invalid_permit2_signature` | The signature doesn't match `from` |
| `invalid_permit2_spender` | `spender` isn't the x402 Permit2 proxy |
| `invalid_transaction_state` | The authorization reuses a nonce that already settled |
| `invalid_upto_evm_payload_settlement_exceeds_amount` | On `/settle`, the actual amount exceeds the signed maximum |
| `invalid_x402_version` | The x402 version in the request isn't supported |
| `permit2_2612_amount_mismatch` | The permit `amount` doesn't equal the signed Permit2 maximum |
| `permit2_amount_mismatch` | On `/verify`, the signed `permitted.amount` doesn't equal `paymentRequirements.amount` |
| `permit2_deadline_expired` | `deadline` is less than 10 seconds away |
| `permit2_invalid_nonce` | The Permit2 nonce is already used onchain |
| `permit2_not_yet_valid` | `witness.validAfter` is in the future |
| `permit2_simulation_failed` | The allowance is short and the permit can't be used: its nonce is stale or its signature is invalid |
| `permit2_token_mismatch` | `permitted.token` doesn't equal `asset` |
| `unsupported_scheme` | The `scheme` isn't `exact` or `upto` |
| `upto_facilitator_mismatch` | `witness.facilitator` isn't an active Circle facilitator for the network |

## Status reasons

This reason string appears in
[`/status`](/api-reference/facilitator-service/get-payment-status) responses as
`reason`.

| Reason | Cause |
| - | - |
| `outcome_unknown` | Facilitator Service couldn't determine whether the payment reached a terminal state |

## HTTP status errors

Some errors use an HTTP status instead of a `200` result.

| Status | Cause |
| - | - |
| `401` | The request has no Circle API key and no seller proof |
| `403` | `/settle` called with a seller proof instead of a Circle API key |
| `403 authorization_expired` | `deadline` passed before Facilitator Service submitted the transfer |
| `409` | The `/settle` call conflicts with an existing payment. See [Repeat settlements](/facilitator-service/how-it-works#repeat-settlements) for the specific conflict modes |
| `412 permit2_allowance_required` | The balance covers the amount, but the Permit2 allowance doesn't and the payment has no permit. Never returned for a `0` settlement. On `/settle`, applies only before a payment exists |
| `503` | Facilitator Service is temporarily at capacity or a dependency is unavailable. Retry with backoff |