Errors and lifecycle

Response shape

On success the body is the data object. There is no envelope — the HTTP status tells you it succeeded.

Success — 201 from create

{
  "userId": "cus_PWEhqXkPKpWXiFd96jGq",
  "userType": "INDIVIDUAL",
  "status": "INITIATED"
}

Every error uses one five-key envelope — for every status code and every error path, including validation, 429, 503 and the Api-Version rejection.

409

{
  "code": 409,
  "message": "Customer holds a balance",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCUS_1606", "message": "Cannot delete a customer that holds a balance", "field": null }
  ]
}

Key	What it holds
`code`	The HTTP status, as an integer (`409`).
`message`	A summary of the failure.
`status`	Always `"ERROR"`.
`data`	Always `null`.
`errors[]`	One `{ code, message, field }` entry per problem.

All field, questionnaire and custom-field errors arrive together, one entry each, and nothing is created. Duplicate email (ERRCUS_1600), duplicate phone (ERRCUS_1601), restricted country (ERRCUS_1605) and a reused share token are checked afterwards, one at a time, and only once the fields are valid — on create and on update:

400 — two problems

{
  "code": 400,
  "message": "Onboarding validation failed",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCUS_1003", "message": "email must be a valid email address", "field": "email" },
    { "code": "ERRCUS_1018", "message": "addressLine1 is required", "field": "addressLine1" }
  ]
}

Branch on errors[].code, never on the message. Every onboarding error has its own frozen ERRCUS_* code — one per field and per reason — listed below. Codes are never renumbered, reused or removed; new ones are only added. There is no name field any more, and no per-status exceptions — 429 and 503 use the same envelope as everything else.

`errors[].field`

The offending input, as a single machine-mappable token — email, company.phone, beneficiaries[0].dob, customFields.whatsappNumber, userType, status, Api-Version, userId, idDocType, document, subjectType, subjectId, uboRef, beneficiaries[0].types. A questionnaire item uses the full path — questionnaire.sections.profileDetails.items.occupation.value. A missing block names the block (company, company.address, beneficiaries), and a cross-beneficiary rule (share total, no UBO) names beneficiaries. Only errors with no single input (a malformed questionnaire structure, a restricted country) carry field: null.

Message wording

Most messages are field-prefixed and lower-cased to match the field token:

Case	`message`	`field`
Email missing	`email is required`	`email`
Email malformed	`email must be a valid email address`	`email`
First name missing	`firstName is required`	`firstName`
Duplicate email	`A user with email '…' already exists`	`email` — `company.email` on a business
Duplicate phone	`A user with phone '…' already exists`	`phone` — `company.phone` on a business

Status codes

Code	Meaning
`201`	Customer created or imported
`200`	Success — get, list, update, kyc-link, document upload, delete
`400`	Validation failed. Nothing is written
`401`	Missing or invalid `API-KEY` — `ERRCORE_1004`
`403`	Key lacks `customers` (`ERRCORE_1005`), or the country is restricted (`ERRCUS_1605`)
`404`	Customer or owner not found. Any `{userId}` that doesn’t resolve to a live customer of yours — unknown, malformed, an internal UUID, deleted, or another partner’s — is `ERRREF_1001`
`405`	Wrong HTTP method for the path
`409`	Conflict — see below
`413`	A file over 5 MB — `ERRCORE_1001` (`File too large`). The whole request is capped at 10 MB
`415`	A non-JSON body type on create or update
`422`	Individual imports only: the supplied email does not match the share token’s verified identity — `ERRCUS_1609`. Currently disabled
`429`	Rate limit exceeded — `ERRCORE_1006`
`500`	Unexpected failure — `ERRCORE_1000`. The whole operation is rolled back. The message is free text and may include internal detail; don’t parse it
`503`	Downstream timed out. Retryable — `ERRCORE_1008`

A 503 on create is safe to retry with the same body — Endl reconciles rather than creating a duplicate.

Conflicts

Cause	Code	Message
A KYC link for an already-verified customer	`ERRCUS_1603`	`This customer's KYC is already completed; a new verification link is not needed`
Changing any field on a completed individual	`ERRCUS_1604`	`This customer's KYC is completed; its details can no longer be changed`
Changing any `company` field on a completed business	`ERRCUS_1604`	`This customer's KYC is completed; verified identity fields can no longer be changed`
Deleting a customer that holds a balance	`ERRCUS_1606`	`Cannot delete a customer that holds a balance` — the amount is never disclosed. Clear the balance first.
A concurrent create or import retry for the same email	`ERRCUS_1602`	`A customer with this email already exists`
Uploading a document before the customer exists	`ERRCUS_1607`	`Create or import the customer before uploading documents`

A duplicate email on a normal create is a 400, ERRCUS_1600. The 409 variant, ERRCUS_1602, is only the concurrent-retry race.

Verification lifecycle

Status	Meaning
`NOT_INITIATED`	Created; verification not yet started
`INITIATED`	Created; documents not yet submitted
`SUBMITTED`	Documents submitted
`IN_REVIEW`	Under review by the provider
`PENDING`	Verification in progress
`COMPLETED`	Approved
`REJECTED`	Rejected
`RESUBMISSION_REQUIRED`	The provider needs something resubmitted

status can also take these five values — the only ones beyond the eight above:

Status	Meaning
`VERIFICATION_IN_PROGRESS`	The verification provider is processing the customer — pre-checks passed, an extra check is running, or the customer was reactivated. No decision yet
`ON_HOLD`	The review is on hold for an internal compliance check before a decision
`AWAITING_UBO_DETAILS`	The provider is waiting for more information from the customer. For a business, typically its beneficial owners’ details
`VERIFICATION_PAUSED`	Verification is temporarily paused — the provider is waiting on an external check, or the applicant was deactivated. It continues once the check completes or the applicant is reactivated
`DELETED`	The verification record was deleted at the provider. It stays like this until verification is reset, when the status goes back to `NOT_INITIATED`

Treat unknown values as in progress. The list filter ?status= accepts only the original eight. For an individual, the customer is submitted for review automatically once every required document step is uploaded — the photo ID, the selfie and the proof of address (a UTILITY_BILL). Until then each upload answers SUBMITTED with a missing list. For a business, Endl submits the business after its first company document, once every owner’s documents are complete — so upload both company groups before the owners’ last document. A business keeps its current status (normally INITIATED) until then, and never returns SUBMITTED.

Locks on completion

The lock is not the same for the two customer types.

Type	What locks once `COMPLETED`
`INDIVIDUAL`	Everything. Any field at all — identity, `currency`, custom fields — returns `409 ERRCUS_1604`. Nothing stays editable.
`BUSINESS`	Everything. Any `company` field returns `409 ERRCUS_1604` (`This customer's KYC is completed; verified identity fields can no longer be changed`). Nothing stays editable.

The questionnaire is not in either list because it is never editable: it is set on create. On update a non-empty questionnaire object is 400 ERRCUS_1303, an empty or non-object one is 400 ERRCUS_1301, and null is ignored — before or after completion.

If you have read that “database-only fields stay editable” after completion, that is no longer true for an individual. currency and custom fields lock with everything else.

Onboarding error codes

Every onboarding error carries its own ERRCUS_* code in errors[].code. The HTTP status, message and field are the same as they would otherwise be — for beneficiaries the code is per field and the index stays in field, so ERRCUS_1206 comes with field: "beneficiaries[2].email".

Range	Covers	HTTP
`ERRCUS_10xx`	Individual customer fields (create, update, import)	`400`
`ERRCUS_11xx`	Business company fields	`400`
`ERRCUS_12xx`	Business beneficiaries	`400`
`ERRCUS_13xx`	Questionnaire and custom fields	`400`
`ERRCUS_14xx`	Documents	`400`
`ERRCUS_15xx`	Request level	`400`
`ERRCUS_16xx`	Onboarding business rules	as listed

Individual customer

Code	`field`	Reason
`ERRCUS_1000`	`userType`	Missing
`ERRCUS_1001`	`userType`	Not supported (only `INDIVIDUAL` on this path)
`ERRCUS_1002`	`email`	Missing
`ERRCUS_1003`	`email`	Invalid format
`ERRCUS_1004`	`firstName`	Missing
`ERRCUS_1005`	`firstName`	Too long (max 100)
`ERRCUS_1006`	`lastName`	Missing
`ERRCUS_1007`	`lastName`	Too long (max 100)
`ERRCUS_1008`	`dateOfBirth`	Missing
`ERRCUS_1009`	`dateOfBirth`	Invalid format (not `DD-MM-YYYY`)
`ERRCUS_1010`	`dateOfBirth`	In the future
`ERRCUS_1011`	`dateOfBirth`	Customer is under 18
`ERRCUS_1012`	`country`	Missing
`ERRCUS_1013`	`country`	Invalid (not ISO 3166-1 alpha-3)
`ERRCUS_1014`	`nationality`	Invalid (not ISO 3166-1 alpha-3)
`ERRCUS_1015`	`taxResidenceCountry`	Invalid (not ISO 3166-1 alpha-3)
`ERRCUS_1016`	`gender`	Invalid (not `M` / `F`)
`ERRCUS_1017`	`phone`	Invalid format (not E.164)
`ERRCUS_1018`	`addressLine1`	Missing
`ERRCUS_1019`	`city`	Missing
`ERRCUS_1020`	`state`	Missing
`ERRCUS_1021`	`postalCode`	Missing. Not required for `ARE`/`HKG` on create. On update, required with any address change, including for `ARE`/`HKG`
`ERRCUS_1022`	`postalCode`	Invalid for the country (format-checked for `USA`, `DEU`, `IND` and `GBR` only)
`ERRCUS_1023`	`shareToken`	Missing (import)
`ERRCUS_1024`	`shareToken`	Invalid (import)

Business company

Code	`field`	Reason
`ERRCUS_1100`	`company`	Missing
`ERRCUS_1101`	`company.companyName`	Missing
`ERRCUS_1102`	`company.registrationNumber`	Missing
`ERRCUS_1103`	`company.type`	Missing
`ERRCUS_1104`	`company.type`	Not an allowed type
`ERRCUS_1105`	`company.phone`	Missing
`ERRCUS_1106`	`company.phone`	Invalid format (not E.164)
`ERRCUS_1107`	`company.website`	Missing
`ERRCUS_1108`	`company.website`	Invalid URL
`ERRCUS_1109`	`company.taxId`	Missing
`ERRCUS_1110`	`company.email`	Missing
`ERRCUS_1111`	`company.email`	Invalid format (create only — `company.email` is not format-checked on update)
`ERRCUS_1112`	`company.incorporatedOn`	Missing
`ERRCUS_1113`	`company.incorporatedOn`	Invalid format (not `DD-MM-YYYY`)
`ERRCUS_1114`	`company.incorporatedOn`	In the future
`ERRCUS_1115`	`company.country`	Missing
`ERRCUS_1116`	`company.country`	Invalid (not ISO 3166-1 alpha-3)
`ERRCUS_1117`	`company.address`	Missing
`ERRCUS_1118`	`company.address.street`	Missing
`ERRCUS_1119`	`company.address.town`	Missing
`ERRCUS_1120`	`company.address.state`	Missing
`ERRCUS_1121`	`company.address.postCode`	Missing (not required for `ARE`, `HKG`)
`ERRCUS_1122`	`company.address.postCode`	Invalid for the country (format-checked for `USA`, `DEU`, `IND` and `GBR` only)
`ERRCUS_1123`	`company.address.country`	Missing
`ERRCUS_1124`	`company.address.country`	Invalid (not ISO 3166-1 alpha-3)
`ERRCUS_1125`	`companyName`	Missing (business import)

Business beneficiaries

Code	`field`	Reason
`ERRCUS_1200`	`beneficiaries`	None provided
`ERRCUS_1201`	`beneficiaries`	No UBO among them
`ERRCUS_1202`	`beneficiaries`	`shareSize` total is over 100
`ERRCUS_1203`	`beneficiaries[i].firstName`	Missing
`ERRCUS_1204`	`beneficiaries[i].lastName`	Missing
`ERRCUS_1205`	`beneficiaries[i].email`	Missing
`ERRCUS_1206`	`beneficiaries[i].email`	Invalid format
`ERRCUS_1207`	`beneficiaries[i].phone`	Invalid format (not E.164)
`ERRCUS_1208`	`beneficiaries[i].dob`	Missing
`ERRCUS_1209`	`beneficiaries[i].dob`	Invalid format (not `DD-MM-YYYY`)
`ERRCUS_1210`	`beneficiaries[i].dob`	In the future
`ERRCUS_1211`	`beneficiaries[i].country`	Missing
`ERRCUS_1212`	`beneficiaries[i].country`	Invalid (not ISO 3166-1 alpha-3)
`ERRCUS_1213`	`beneficiaries[i].shareSize`	Not between 0 and 100
`ERRCUS_1214`	`beneficiaries[i].types`	Not supported (only `ubo`)
`ERRCUS_1215`	`beneficiaries[i].address`	Missing
`ERRCUS_1216`	`beneficiaries[i].address.street`	Missing
`ERRCUS_1217`	`beneficiaries[i].address.town`	Missing
`ERRCUS_1218`	`beneficiaries[i].address.state`	Missing
`ERRCUS_1219`	`beneficiaries[i].address.postCode`	Missing (not required for `ARE`, `HKG`)
`ERRCUS_1220`	`beneficiaries[i].address.postCode`	Invalid for the country
`ERRCUS_1221`	`beneficiaries[i].address.country`	Missing
`ERRCUS_1222`	`beneficiaries[i].address.country`	Invalid (not ISO 3166-1 alpha-3)

Questionnaire and custom fields

Question keys come from the verification level, so these codes are per reason, and field names the exact question — for example questionnaire.sections.profileDetails.items.occupation.value.

Code	`field`	Reason
`ERRCUS_1300`	`questionnaire`	Missing (required on create)
`ERRCUS_1301`	`null`	Badly shaped (not an object, no sections, or a section without items)
`ERRCUS_1302`	`null`	Not supported for this customer’s level
`ERRCUS_1303`	`questionnaire`	Sent on an update (it cannot be updated)
`ERRCUS_1304`	question path	Unknown question
`ERRCUS_1305`	question path	Required answer missing
`ERRCUS_1306`	question path	Not one of the allowed options
`ERRCUS_1307`	question path	Not a 3-letter code
`ERRCUS_1308`	question path	Blank, or not a value
`ERRCUS_1309`	question path	Wrong shape (single value vs values array)
`ERRCUS_1310`	question path	File question answered as text (a file item can’t be sent through the JSON API)
`ERRCUS_1320`	`customFields`	Not an object
`ERRCUS_1321`	`customFields.<name>`	Unknown custom field
`ERRCUS_1322`	`customFields.<name>`	Required custom field missing (e.g. whatsappNumber)
`ERRCUS_1323`	`customFields.<name>`	Empty value

Documents

Code	`field`	Reason
`ERRCUS_1400`	`document`	The `document` part was sent but empty. A request with no `document` part is rejected with a `400` before validation (no `ERRCUS_` code)
`ERRCUS_1401`	`document`	Reserved, not returned in practice — a file over 5 MB is `413 ERRCORE_1001`
`ERRCUS_1402`	`document`	Not a JPEG, PNG or PDF
`ERRCUS_1403`	`document`	Content does not match its type
`ERRCUS_1404`	`null`	File could not be read
`ERRCUS_1405`	`idDocType`	Sent but blank. Omitted entirely → `400 ERRCORE_1001` (`idDocType is required`)
`ERRCUS_1406`	`idDocType`	Not an allowed type (see document types). Not returned on owner uploads, where `idDocType` is not validated
`ERRCUS_1407`	`subjectType`	Not `COMPANY` or `UBO` (business upload)
`ERRCUS_1408`	`subjectId`	Missing when `subjectType` is `UBO`

The document country uses ERRCUS_1012 (sent but blank) and ERRCUS_1013 (invalid). Omitted entirely, it is 400 ERRCORE_1001 (country is required).

Request level

Code	`field`	Reason
`ERRCUS_1500`	`null`	Create: the body is valid JSON but not an object (e.g. `[]`)
`ERRCUS_1501`	`null`	Create: a field has the wrong JSON type or shape
`ERRCUS_1502`	`null`	Update with nothing to apply — including a missing body, or one that isn’t an object
`ERRCUS_1503`	`status`	Invalid status filter on the customer list

Body	Create	Update
Missing	`400 ERRCORE_1001` (`Malformed or missing request body`)	Treated as empty — `400 ERRCUS_1502`
Not valid JSON	`400 ERRCORE_1001`	`400 ERRCORE_1001`
Valid JSON but not an object (e.g. `[]`)	`400 ERRCUS_1500`	Treated as empty — `400 ERRCUS_1502`
A field with the wrong JSON type	`400 ERRCUS_1501`	—

Onboarding business rules

Code	HTTP	`field`	Reason
`ERRCUS_1600`	`400`	`email` / `company.email`	Email already used by another customer
`ERRCUS_1601`	`400`	`phone` / `company.phone`	Phone already used by another customer
`ERRCUS_1602`	`409`	`email` / `company.email`	A customer with this email already exists
`ERRCUS_1603`	`409`	`null`	KYC already completed — a new verification link is not needed
`ERRCUS_1604`	`409`	`null`	Customer locked after verification — details can no longer be changed
`ERRCUS_1605`	`403`	`null`	Onboarding not permitted for this country
`ERRCUS_1606`	`409`	`null`	Customer still holds a balance — cannot be deleted
`ERRCUS_1607`	`409`	`null`	Customer not created or imported yet (document upload)
`ERRCUS_1608`	`404`	`uboRef`	UBO is not a beneficiary of this company
`ERRCUS_1609`	`422`	`null`	Imported identity does not match the supplied email. Individual imports only; currently disabled
`ERRCUS_1610`	`400`	`null`	Business endpoint called for an individual customer

Verification-provider errors

Errors from the verification step that you can act on keep their own ERRCOMP_* code, message and HTTP status, rather than collapsing into a generic 500:

HTTP	`errors[].code`	`message`	Meaning
`404`	`ERRCOMP_2010`	`Applicant not found`	No identity record exists yet for this customer
`409`	`ERRCOMP_2011`	`Documents not approved`	Required documents have not passed review yet
`403`	`ERRCOMP_2021`	`Onboarding blocked`	This applicant cannot be onboarded
`503`	`ERRCOMP_2022`	`Provider temporarily unavailable`	Temporary — retry shortly

409

{
  "code": 409,
  "message": "Documents not approved",
  "status": "ERROR",
  "data": null,
  "errors": [
    { "code": "ERRCOMP_2011", "message": "Documents not approved", "field": null }
  ]
}

Other provider failures are a 500 ERRCORE_1000. The 500 message is free text and may include internal detail; don’t parse it. A verification-service failure returns Service temporarily unavailable, please try again (503 ERRCORE_1008 on a timeout).

Codes that are not onboarding-specific

These keep their ERRCORE_*, ERRREF_* or ERRCOMP_* code:

Situation	Code
Missing or invalid `API-KEY`	`ERRCORE_1004`
Key lacks the `customers` permission	`ERRCORE_1005`
Unknown, malformed, blank, deleted, or another partner’s `{userId}`	`404 ERRREF_1001`, field `userId`
Rate limit	`ERRCORE_1006`
A file over 5 MB — `413`	`ERRCORE_1001` (`File too large`)
Verification-provider errors	`ERRCOMP_*` — above
Internal or unavailable	`ERRCORE_1000`, `ERRCORE_1008`, `ERRCORE_1009`

Introduction

Endpoints

Errors and lifecycle

Response shape

`errors[].field`

Message wording

Status codes

Conflicts

Verification lifecycle

Locks on completion

Onboarding error codes

Individual customer

Business company

Business beneficiaries

Questionnaire and custom fields

Documents

Request level

Onboarding business rules

Verification-provider errors

Codes that are not onboarding-specific

​Response shape

​errors[].field

​Message wording

​Status codes

​Conflicts

​Verification lifecycle

​Locks on completion

​Onboarding error codes

​Individual customer

​Business company

​Business beneficiaries

​Questionnaire and custom fields

​Documents

​Request level

​Onboarding business rules

​Verification-provider errors

​Codes that are not onboarding-specific

Response shape

`errors[].field`

Message wording

Status codes

Conflicts

Verification lifecycle

Locks on completion

Onboarding error codes

Individual customer

Business company

Business beneficiaries

Questionnaire and custom fields

Documents

Request level

Onboarding business rules

Verification-provider errors

Codes that are not onboarding-specific