KYC: error codes

This page lists the error codes returned by process images and session status. Results of database checks, such as AML screening, are not part of this list: they are read separately, see below.

A code consists of a category in square brackets and the error name, for example [document] cropped. In the answer the codes arrive as strings in the errors list of the session or of a step:

{
  "errors": [
    "[fraud] mobile device",
    "[document] text fields not visible"
  ]
}

The "What to do" texts can be shown to the user as a hint. Branch on the code, never on any message text. See response format and errors.

General image errors: `[general]`

Code	Meaning	What to do
`[general] bad image`	The uploaded file is not an image.	Send a photo in JPEG or PNG format.
`[general] too small image`	The image is too small to be recognized.	Take a photo in a higher resolution.
`[general] no documents on image`	No document was found in the image.	Make sure you photograph the required document.
`[general] not a selfie`	No face was found outside the document.	Wipe the camera and take a new photo. The face must be in focus and clearly visible.
`[general] low light`	The image is too dark.	Add more light or move to a brighter place.
`[general] black and white image`	The image is black and white.	Do not use filters. The photo must be in color.
`[general] too many faces`	More faces than expected were found in the document image.	Photograph only the document. There must be no other people in the background.
`[general] age requirement mismatch`	The age does not meet the requirements of the scenario.	The check cannot be passed now.
`[general] too many tries`	The allowed number of attempts to upload this type of image is exceeded.	No attempts are left in this session. A new check needs a new session.
`[general] data mismatch`	The full name or the date of birth differ between the steps of the session or from the questionnaire data. The step fails.	Use the documents of one person and check the questionnaire data.

Document errors: `[document]`

Code	Meaning	What to do
`[document] unknown document type`	The document type in the image is not recognized.	Make sure you photograph the required document.
`[document] bad document type`	The document is recognized but does not fit this step of the scenario.	Photograph the type of document that is requested.
`[document] bad pages`	The wrong page of the document was photographed.	Photograph the required spread, for example the main spread of the passport.
`[document] too small image`	The document takes up too small a part of the frame.	Move the camera closer to the document.
`[document] cropped`	The document is not fully visible.	Hold the camera further away. The whole document must fit in the frame.
`[document] bad quality`	The image quality is too low for recognition.	Wipe the camera and take a new photo in focus.
`[document] text fields not visible`	The document fields are not visible.	Wipe the camera and take a new photo. The fields must not be covered by fingers or glare.
`[document] text field has low confidence`	A field was recognized with low confidence.	Wipe the camera and take a new photo in focus.
`[document] bad mrz checksum`	The data of the machine readable zone failed the checksum check.	Take a new photo. The lines of the zone must be fully visible and sharp.
`[document] no face`	The photo of the holder was not found on the document.	Make sure the photo in the document is clearly visible.
`[document] no signature`	The document has no signature.	The document is invalid. Use another one.
`[document] no stamp`	The document has no stamp.	The document is invalid. Use another one.
`[document] no required objects`	The document lacks required elements.	The document is invalid. Use another one.
`[document] no required fields`	The document lacks required fields.	The document is invalid. Use another one.
`[document] expired`	The document has expired.	Use a valid document.
`[document] other error`	The document does not meet the requirements.	Present another document.

Signs of forgery: `[fraud]`

Code	Meaning	What to do
`[fraud] display or screen`	A screen was photographed.	Photograph the original document, not its image on a screen.
`[fraud] mobile device`	A mobile device screen is in the frame.	Photograph the original document, not its image on a screen.
`[fraud] image printed`	The image looks like a photocopy or a printout.	Photograph the original document.
`[fraud] image edited`	The image was processed in a graphics editor.	Photograph the original document and send the photo without editing.
`[fraud] document modified`	The document is physically altered: corrections or pasted-in elements.	Use a document without corrections or pasted-in elements.
`[fraud] bad document photo`	The photo in the document looks suspicious.	Do not cover the photo or the area around it with fingers or objects.
`[fraud] document damaged`	The document is damaged.	The document is invalid. Use another one.
`[fraud] logical mismatch`	Logical inconsistencies were found in the document data.	The check failed.
`[fraud] manipulation detected`	Different documents, or documents of different people, were uploaded in the session.	Repeat the photos as the scenario requires, using the same document.
`[fraud] multiple documents`	Different documents of the same type were uploaded in the session.	The check failed.
`[fraud] black list`	The user was found in the blacklist.	The check failed.

Face check errors: `[face]`

Code	Meaning	What to do
`[face] bad face matching`	The face on the selfie does not match the photo in the document.	Take a selfie holding the document. The face and the document must be fully visible.
`[face] not all faces found`	Not all faces required for the check were found.	Wipe the camera and take a new photo in focus.
`[face] face out of frame`	The face is cut off by the edge of the frame.	Hold the phone so that the whole face fits in the frame.
`[face] face occluded`	The face is covered by the document.	Hold the document next to the face without covering it.
`[face] is deepfake`	The face in the image shows signs of generation or substitution.	Use a real photo without editing.
`[face] is not alive`	The image failed the liveness check.	Take the check yourself, in front of the camera, in good light.
`[face] reference session unusable`	The face from the earlier session that the selfie is compared with is not available for comparison.	Comparison with this session is not possible. The check needs a new session with a document.

Questionnaire errors: `[questionnaire]`

Code	Meaning	What to do
`[questionnaire] bad name`	The full name has fewer than two words or is too long, or a required field is empty.	Enter the full name and fill in the required fields.
`[questionnaire] bad age`	The date of birth is invalid or the age is outside the allowed range.	Check the date of birth.
`[questionnaire] session not found`	The questionnaire record was not found.	Fill in the questionnaire again.
`[questionnaire] questionnaire not completed`	The questionnaire was not completed.	Complete the questionnaire.
`[questionnaire] wrong code`	The confirmation code is wrong.	Check the code and enter it again.
`[questionnaire] code expired`	The code has expired.	Request a new code.
`[questionnaire] code locked`	Too many wrong attempts. Code entry is temporarily blocked.	Wait and request a new code.
`[questionnaire] code resend cooldown`	A new code cannot be requested yet.	Wait and request the code later.
`[questionnaire] confirm required`	The email or phone was not confirmed with a code, or was changed after confirmation.	Confirm the contact with a code.

System errors: `[system]`

Code	Meaning	What to do
`[system] balance too low`	The balance is insufficient.	Top up the account balance and try again.
`[system] service timeout`	The service did not respond in time.	Send the image again.
`[system] exception`	Internal service error.	Send the image again. If the error repeats, contact support.

Database check results

The verdicts of database checks, such as AML screening, are not in the body of a session. Read them from database check results or from the DATABASE_CHECKS_COMPLETE webhook, and decide on the outcome of each check. See AML screening.

A code that is not in this list

Treat an unknown code as a failure with an unknown reason, and write to support with the session identifier. See support and contacts.

KYC: error codes

General image errors: [general]

Document errors: [document]

Signs of forgery: [fraud]

Face check errors: [face]

Questionnaire errors: [questionnaire]

System errors: [system]