iOS SDK unhappy paths
Last updated: October 28, 2024
There are several possible unhappy paths in the iProov claim process. It is essential that you provide user guidance, directions, and education to ensure successful retries and to prevent drop offs. There are two types of unhappy responses during a claim lifecycle:
Select an SDK version
To display errors and failures that are applicable to your environment, select a version of the SDK:
Errors
An error occurs when a user is unable to complete an iProov verification process. For example, the internet connection failed or the user aborted the process.
Corrective measures, user guidance, and retries should be implemented.
| Error Code | Description | Suggested resolution action |
|---|---|---|
captureAlreadyActive
|
An iProov capture is already in progress. | Wait until the previous iProov claim has completed and try again. |
networkError(String?)
|
An error occurred with communications to the server. Typically indicates a device connectivity issue, for example, the user's session has timed out or the internet service has been lost. |
Prompt the user to reconnect to a suitable cellular or WiFi network and try again. |
cameraPermissionDenied
|
The user did not allow access to the camera when prompted. | Prompt the user to enable the camera permission (via settings). |
serverError(String?)
|
The token was invalidated server-side or some other unrecoverable server error occurred. |
End the journey and display this message: Try again later. |
unexpectedError(String)
|
An unrecoverable error has occurred during the transaction. |
End the journey and provide steps for the user to restart on a compatible device. Direct the user to an FAQ or support channel detailing the device requirements. |
Failures
A failure occurs when iProov successfully processes a claim but a user's face cannot be authenticated. For example, the user did not pass the biometric tests and/or machine learning models.
Retry measures are recommended, however, caution should be taken to ensure that potential fraudsters are not given unlimited attempts. For details see API retry mechanism.
| Failure code | Description | Suggested resolution action | Assurance types |
|---|---|---|---|
unknown
|
The claim failed for an unknown reason. | Try again. | GPA and LA |
too_much_movement
|
The user is moving too much during the claim. | Keep still. | GPA |
too_bright
|
Possible causes:
|
Move somewhere darker. |
GPA Available soon in LA. |
too_dark
|
The user’s environment is too dark. | Move somewhere brighter. |
GPA Available soon in LA. |
misaligned_face
|
User's face is not aligned with the oval. | Keep your face in the oval. | GPA |
eyes_closed
|
One or both of the user's eyes are not open. | Keep your eyes open. |
GPA Available soon in LA. |
face_too_far
|
The user is too far from the device. | Move your face closer to the screen. | GPA |
face_too_close
|
The user is too close to the device. | Move your face farther from the screen. | GPA |
sunglasses
|
The user is wearing glasses with dark lenses. | Remove sunglasses. |
GPA Available soon in LA. |
obscured_face
|
The user's face is not completely visible. | Remove any face coverings. |
GPA Available soon in LA. |
userTimeout
|
Try again. | GPA and LA | |
notSupported
|
Device is not supported. | GPA and LA | |
ambiguous_outcome
|
The iProov claim has resulted in a negative outcome.  Warning
Could indicate a fraudulent attempt. |
If in the retry attempt quota, offer a retry. |
|
motion_too_much_movement
|
The user is moving too much during the claim. |
Provide user guidance to remain still during the claim. Retry the claim. |
|
lighting_flash_reflection_too_low
|
The ambient light is too strong or the screen brightness is too low. |
Ask the user to turn their screen brightness up to maximum or move out of the direct sunlight. Retry the claim. |
|
lighting_backlit
|
A strong light source has been detected behind the user. |
Ask the user to adjust their position relative to the light source. Retry the claim. |
|
lighting_too_dark
|
The user’s environment is too dark. |
Ask the user to move to an area with more light. Retry the claim. |
|
lighting_face_too_bright
|
Too much light has been detected on the user’s face. |
Ask the user to adjust their position relative to the light source. Retry the claim. |
|
motion_too_much_mouth_movement
|
The user is talking during the claim process. |
Ask the user to refrain from speaking during the claim process. Retry the claim. |
Next step
