Onboarding API: Error Messages
This page lists common validation messages returned by the Onboarding API, with the status code, an endpoint where each occurs, and the cause. For field formats, see Validation Rules for Individuals and Validation Rules for Legal Entities.
Error Response Structure
An error response contains the following keys.
| Key | Description |
|---|---|
statusCode | The HTTP status code. |
timestamp | The time of the error. |
method | The HTTP method of the request. |
path | The path of the request. |
message | An array of error messages. |
Example of the message key:
"message": ["phoneNumber is too short"]This structure differs from the Error, Code, Msg, Prio and INT_MSG structure of the payment API.
A format error names the field it refers to. A business-rule error, for example, a date of birth before 1920, returns a message without a field name. Some business-rule errors return status 500.
Format and content errors
| Message | Status | Endpoint | Cause |
|---|---|---|---|
<field> must be a valid ISO 3166-1 alpha-2 code or one of the following codes: XK | 400 | POST /accounts/legal-entity | A country field (birthCountry, address.country or nationalities) is not a valid code. Use GB for the United Kingdom: UK is rejected. |
individual.birthDate must be a valid ISO 8601 date string | 400 | POST /accounts/individual | The birth date is not in ISO 8601 format. Use YYYY-MM-DD or a full timestamp. DD/MM/YYYY is rejected. |
phoneNumber is not valid | 400 | POST /onboardings/individual | The number has no country code, or it is not valid for its country, even if its length is correct. |
phoneNumber is too short | 400 | POST /onboardings/individual | The number has fewer digits than the country allows. |
phoneNumber is too long | 400 | POST /onboardings/individual | The number has more digits than the country allows. |
status must be a valid enum value | 400 | POST /onboardings/company | politicalExposure.status is missing. Send it for the legal representative and for each UBO. |
ubo otherName must be set | 400 | POST /onboardings/company | The otherName of a UBO contains no valid name character, for example 123 or @@@. The message does not give the UBO index. |
ubos.0.otherName should not be empty | 400 | POST /onboardings/company | The otherName of a UBO is an empty string. Omit the field instead. |
website is not in valid format | 400 | POST /onboardings/company | legalEntity.website is not a single valid URL. Two URLs, separated by a space or a comma, are rejected. |
Business Rule Errors
| Message | Status | Endpoint | Cause |
|---|---|---|---|
year of birth cannot be less than 1920 | 500 | POST /accounts/individual, POST /accounts/legal-entity (legal representative) | The year of birth is before 1920. 1920 is accepted. |
date of birth cannot be today or in the future | 500 | POST /accounts/individual, POST /accounts/legal-entity (legal representative) | The date of birth is in the future. |
"account has already an onboarding ongoing for this profile" | 500 | POST /onboardings/company | An onboarding was already created for this account and profile. The quotation marks are part of the message. |
individual account with same identity already exists - id: <existing id> | 409 | POST /accounts/individual | An account with the same identity exists. The message contains the id of the existing account. |
Identity conflict on POST /accounts/individual
POST /accounts/individualThe API returns 409 when an account with the same identity exists. A new account is created when the first name, the birth date, or the birth country differs. No new account is created when only the email, the walletId, the nationalities, the profile, or the letter case of the last name differs.
To give an existing person a second profile, use POST /accounts/individual/{accountId}/profiles. See Onboarding for Multiple Profiles & Wallets.