Handling Failures

Reference for Flutter Face Liveness failure handling. Learn CerttaLivenessFailure types, cause values, and how to map failures to clear user guidance.

This guide covers caf_sdk 2.4.0 and above (Certta DevX). For the previous CafSdk sequential flow, see the legacy documentation.

When a liveness check fails, the SDK emits CerttaLivenessEvent.failed with a CerttaLivenessFailure object. This object contains a cause parameter (a stable code for mapping logic) and, for recognition failures, a description field with user-facing text.

Understanding and handling these fields is critical for providing clear, actionable feedback so users can correct the issue and try again.

The failure models

Both capture-level and recognition-level failures share the same CerttaLivenessFailure type. Use type to distinguish them:

type	Meaning
ImageCaptureFailure	Image capture failed. No signed image (response) is available.
FaceRecognitionFailure	Capture succeeded, but recognition or authentication failed. response holds the signed payload. description provides a human-readable message.

For FaceRecognitionFailure, cause is normalized to uppercase by the Flutter plugin. Use cause for conditional logic and description (or your own localized copy) for messages shown to end users.

Ensure the JWT response is evaluated on the backend. This process must include validating the token's signature and verifying the isAlive and isMatch fields. Do not perform these validations on the client side.

Using cause and description

The cause parameter returns a stable constant string (for example "TOO_DARK" or "FACE_TOO_FAR"). Do not display cause directly to end users.

For FaceRecognitionFailure, prefer description as a fallback when you do not maintain a custom mapping. Otherwise, map cause to a localized, user-friendly message in your UI.

Available failure causes

When using the iProov provider, if capture succeeds but the engine fails to authenticate or process the face, the SDK returns a FaceRecognitionFailure.

Possible cause values:

Cause	Description
UNKNOWN	Generic failure
TOO_MUCH_MOVEMENT	Excessive head motion
TOO_BRIGHT	Over-illumination
TOO_DARK	Low light conditions
MISALIGNED_FACE	Face alignment failure
FACE_TOO_FAR	Face too distant
FACE_TOO_CLOSE	Face too close
SUNGLASSES	Eye-obscuring eyewear
OBSCURED_FACE	Partial face obstruction
EYES_CLOSED	Closed eyes during capture
MULTIPLE_FACES	Multiple faces detected
BACKGROUND_ISSUE	Unsuitable background
DEVICE_ISSUE	Incompatible device
EYEWEAR	Eyewear detected
FACE_NOT_FOUND	Face detection failure
FRAMES_BLURRY	Blurry frames detected
MOTION_ISSUE	Device motion error
LIGHTING_ISSUES	Poor lighting conditions
REJECTED	Transaction rejected
SYSTEM_ERROR	Internal system error
TIMEOUT	Session timeout
USER_NOT_FOUND	User lookup failure
DEVICE_RESTART	Device state error
PROCESSING_FAULT	Processing error

The previous CafSdk docs also marked which causes apply to GPA vs LA providers. Treat the table above as the full set of identifiers you may receive; map unknown values to a generic retry message.

Example implementation

String messageForLivenessFailure(CerttaLivenessFailure failure) {
  if (failure.type == 'ImageCaptureFailure') {
    debugPrint('Capture failed before reaching the server.');
  } else if (failure.type == 'FaceRecognitionFailure') {
    debugPrint('Server rejected the capture. Response: ${failure.response}');
    if (failure.description != null && failure.description!.isNotEmpty) {
      return failure.description!;
    }
  }

  switch (failure.cause) {
    case 'TOO_DARK':
      return "It's a bit too dark. Please move to a brighter room.";
    case 'FACE_TOO_FAR':
      return 'Please bring the phone closer to your face.';
    case 'EYES_CLOSED':
      return 'Please keep your eyes open and look directly at the camera.';
    case 'MULTIPLE_FACES':
      return 'Ensure you are the only one in the frame.';
    case 'TIMEOUT':
      return 'Time ran out. Please try again when you are ready.';
    case 'REJECTED':
    case 'FACE_AUTHENTICATION':
      return "We couldn't verify your face. Please try again.";
    default:
      return 'An unexpected error occurred (${failure.cause}). Please try again.';
  }
}