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

# End User Onboarding API error codes

> Numeric error codes returned by the End User Onboarding API, with HTTP status, public message, and partner action.

The End User Onboarding API returns an HTTP status and a JSON body with a
numeric `code` and a `message`. The `message` is the generic HTTP phrase for
that status, such as `Not found` or `Gateway timeout`. Use `code` to tell apart
errors that share one HTTP status and one phrase.

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

## Two not found responses

Both of these responses use HTTP 404 and `message: "Not found"`. The `code`
tells them apart.

**Unknown application (`181103`):**

```json theme={null}
{
  "code": 181103,
  "message": "Not found"
}
```

**Device check missing (`181110`):**

```json theme={null}
{
  "code": 181110,
  "message": "Not found"
}
```

## Shared status codes

| HTTP status | Codes | How to tell them apart |
| - | - | - |
| `404` | `181103`, `181110` | `181103` is an unknown application. `181110` means the required device check was not run. |
| `504` | `181109`, `181111` | `181109` is an identity verification (IDV) wait. `181111` is a device-check wait. |
| `409` | `181104`, `181105` | `181104` is the wrong application state. `181105` is idempotency key reuse. |
| `422` | `181100`, `181101` | `181100` is field validation. The body includes `errors[]` with per-field `field`, `code`, `message`, and `section`. `181101` means one or more sections are incomplete. |

## Error codes (181100-181111)

| Error code | HTTP code | Error message | Resolution |
| - | - | - | - |
| `181100` | `422` | `Unprocessable entity` | Field validation failed. Read `errors[]`, fix the payload, then retry. |
| `181101` | `422` | `Unprocessable entity` | One or more sections are incomplete. Complete every required section, then retry. |
| `181102` | `400` | `Bad request` | Fix the malformed request body or headers, then retry. |
| `181103` | `404` | `Not found` | Confirm the application ID exists and that your API key can access it. |
| `181104` | `409` | `Conflict` | Fetch the application and retry when its status allows this operation. |
| `181105` | `409` | `Conflict` | Retry with a new `X-Idempotency-Key` after an idempotency conflict. |
| `181106` | `403` | `Forbidden` | Use an API key that includes the required scope. |
| `181107` | `401` | `Unauthorized` | Send a valid Bearer token in the `Authorization` header. |
| `181108` | `500` | `Internal server error` | The device-check lookup failed. The application status is unchanged. Don't treat this as a decline. Retry later. See [Collect device risk signals](/end-user-onboarding/howtos/collect-device-risk-signals). |
| `181109` | `504` | `Gateway timeout` | Identity verification didn't reach a decision in time. Don't treat this as a missing device check. Retry later. |
| `181110` | `404` | `Not found` | The device check wasn't run. The application status is unchanged. Run the device check, then retry submit. See [Collect device risk signals](/end-user-onboarding/howtos/collect-device-risk-signals). |
| `181111` | `504` | `Gateway timeout` | The device check hasn't finished. The application status is unchanged. Retry later. Don't treat this as a missing device check. Don't treat this as an IDV timeout. See [Collect device risk signals](/end-user-onboarding/howtos/collect-device-risk-signals). |

If a Partner API code is not allowlisted, the response uses `code: -1`. Retry
with backoff. Confirm that the expected code is in this catalog.