End User Onboarding API error codes

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.

Two not found responses

Both of these responses use HTTP 404 and message: "Not found". The code tells them apart. Unknown application (181103):

{
  "code": 181103,
  "message": "Not found"
}

Device check missing (181110):

{
  "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.

​Two not found responses

​Shared status codes

​Error codes (181100-181111)

Two not found responses

Shared status codes

Error codes (181100-181111)