Error Handling

Overview

Most of the MobbScanAPI callbacks provide a MobbScanAPIError instance as their final parameter whenever an operation fails or requires handling.

A MobbScanAPIError object contains the following fields and methods:

• MobbScanAPIErrorCode: Enum representing the high-level category of the error.
• getErrorReason(): Returns a nullable ErrorReason value representing the specific reason returned by the backend. ErrorReason is an extensible class, not a Java enum. Its predefined values include NOT_VALID_DOCUMENT, NOT_VALID_IMAGE, TOO_MANY_FEW_LINES, EMPTY_CORNERS, QR_NOT_DETECTED, FACE_NOT_DETECTED, MRZ_NOT_DETECTED, BLURRING_CHECK_NOT_PASSED, ERROR_FRONT_DOCUMENT_SIDE_DUPLICATED, and ERROR_BACK_DOCUMENT_SIDE_DUPLICATED. The backend may also return other reason strings.
• extraInfo: A Map<String, String> containing additional contextual details (such as errorDetails for specific failed validation checks).

Programmatic Error Reason (ErrorReason)

To inspect why a verification, matching, or document scan failed programmatically, first check that the callback's error parameter is not null. The backend may omit a reason, in which case getErrorReason() returns null. Compare predefined reasons with ErrorReason values; compare other backend reasons with getValue():

Kotlin

Java

val reason = error?.getErrorReason()
if (reason == null) {
    // No error was returned, or the backend did not provide a reason
} else if (reason == ErrorReason.NOT_VALID_DOCUMENT) {
    val details = error?.getExtraInfo()?.get("errorDetails")
    // Handle specific document validation failures (e.g. expired document, MRZ check failed)
} else if (reason.getValue() == "LIVENESS_FAILED") {
    // Handle facial liveness verification failure
} else if (reason.getValue() == "MATCHING_FAILED") {
    // Handle face-to-document matching failure
} else {
    // Handle other backend reasons or use a generic fallback
}

if (error != null) {
    ErrorReason reason = error.getErrorReason();
    if (ErrorReason.NOT_VALID_DOCUMENT.equals(reason)) {
        String details = error.getExtraInfo() == null
                ? null : error.getExtraInfo().get("errorDetails");
        // Handle specific document validation failures
    } else if (reason != null && "LIVENESS_FAILED".equals(reason.getValue())) {
        // Handle facial liveness verification failure
    } else if (reason != null && "MATCHING_FAILED".equals(reason.getValue())) {
        // Handle face-to-document matching failure
    } else if (reason != null) {
        // Handle other backend reasons or use a generic fallback
    }
}

Error Codes (MobbScanAPIErrorCode)

The following table shows the available MobbScanAPIErrorCode values and their meaning:

Code	Meaning
UNEXPECTED_ERROR	Something unexpected happened during the process
CONNECTION_ERROR	A network connection error happened
TIMEOUT_ERROR	The process timeout expired
WRONG_PARAMETERS_ERROR	Some of the parameters are not valid
SCANNING_PROCESS_CANCELLED	The user cancelled the scanning process
DOCUMENT_NOT_CLASSIFIED	The system is not able to classify the document (only applicable for generic document types, i.e. ESP)
DOCUMENT_NOT_VALID	The document did not pass the validations (applicable when specific validations are activated)
LICENSE_ERROR	The license is not valid or has not been configured
PERMISSION_ERROR	The required app permissions have not been granted
API_NOT_INITIALIZED_ERROR	MobbScanAPI was not properly initialised
DEVICE_NOT_COMPATIBLE	Device does not fulfill the minimum requirements
NOT_AVAILABLE_IN_OFFLINE_MODE	The process is only available online
CAPTURE_FACE_ERROR	Facial detection could not accomplished
STARTING_VIDEO_ERROR	An error ocurred when starting the unattended video
FINISHING_VIDEO_ERROR	An error ocurred when finishing the unattended video
USER_CANCELLED_ERROR	The user cancelled any process (document detection, face validation...)
VIDEO_RECORDING_ERROR	An error ocurred while the unattended video is being recorded
ANTISPOOFING_ERROR	The antispoofing mechanism cannot ensure the user is genuine
VIDEO_LIVENESS_VIDEO_NO_FACE	No faces has been found in the face validation video
VIDEO_LIVENESS_NO_MOVEMENT	No face movement has been found in the face validation video
VIDEO_LIVENESS_INVALID_FORMAT	The video provided for the face validation process does not match the required format
VIDEO_LIVENESS_MULTIPLE_FACES	More than one face has been detected in the face validation video
VIDEO_LIVENESS_LIVENESS_ERROR	An error ocurred while performing the face detection in the face validation video
VIDEO_LIVENESS_MATCHING_ERROR	An error ocurred while performing the face matching in the face validation process
VIDEO_LIVENESS_WRONG_SCANID	Provided scanId does not correspond to a valid started process
UNATTENDED_VIDEO_TIMEOUT	The unattended video process exceeded the timeout
UNATTENDED_VIDEO_CANCEL_ERROR	The unattended video cancellation went wrong

Extra Information (extraInfo)

When a process fails validation checks, extraInfo["errorDetails"] contains the specific failed validation rules.

This information is also preserved in unattended video flows (VideoUnattendedFinishedListener):

Kotlin

Java

val failedValidations = error?.getExtraInfo()?.get("errorDetails")
println("Failed validations: $failedValidations")

String failedValidations = error == null || error.getExtraInfo() == null
        ? null : error.getExtraInfo().get("errorDetails");
System.out.println("Failed validations: " + failedValidations);

The output will contain the list of failed checks:

Failed validations: validationMRZ, validationDocumentNotExpired, validationBothSidesMatchScore