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

# 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. Do not treat this as a decline. Retry later.                                                      |
| `181109`   | `504`     | `Gateway timeout`       | Identity verification did not reach a decision in time. Do not treat this as a missing device check. Retry later.                                                      |
| `181110`   | `404`     | `Not found`             | The device check was not run. The application status is unchanged. Run the device check, then retry submit.                                                            |
| `181111`   | `504`     | `Gateway timeout`       | The device check has not finished. The application status is unchanged. Retry later. Do not treat this as a missing device check. Do not treat this as an IDV timeout. |

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.