Biometric Authentication Warnings

Biometric Authentication combines a liveness check with an optional 1:1 face match against the stored portrait_image. Each step emits its own warnings in the V3 decision payload. This page lists every code, where it appears, and how thresholds translate into a final session status.

Overview

When a biometric authentication session runs, Didit:

Captures a live selfie using 3D Action, Flash, or Passive Liveness (method: ACTIVE_3D, FLASHING, or PASSIVE).
Extracts the largest face from the capture and scores its liveness.
If the workflow includes Face Match, compares the captured face against the stored portrait_image.
Writes the outcome of each step plus any warnings into the session decision.

Warnings keep the shared warning object shape used across the platform: feature, risk, additional_data, log_type, short_description, long_description, and node_id.

Where warnings appear

Decision response key	Feature tag on the warning	When it fires
`liveness_checks[].warnings[]`	`LIVENESS`	Liveness scoring, face quality, luminance, multiple-faces, and blocklist / allowlist / duplicate-face checks.
`face_matches[].warnings[]`	`FACEMATCH`	Face match against the stored `portrait_image`.

In a typical biometric-auth session there is one item in each array. In multi-instance workflows the node_id on each warning disambiguates which step produced it.

Automatic decline conditions

The following warnings always decline their step (log_type: "error") regardless of how you configured the workflow:

Risk	Feature	Why it auto-declines
`FACE_IN_BLOCKLIST`	`LIVENESS`	The face matched an entry in your face blocklist.
`NO_FACE_DETECTED`	`LIVENESS`	No face was located during the liveness capture, or the user exhausted the capture retry attempts.
`LIVENESS_FACE_ATTACK`	`LIVENESS`	A presentation attack was detected (mask, screen replay, deepfake-class spoof).
`NO_REFERENCE_IMAGE`	`FACEMATCH`	No reference image was available to run the comparison. When this fires, `LOW_FACE_MATCH_SIMILARITY` is suppressed.

When NO_FACE_DETECTED fires, LOW_LIVENESS_SCORE is suppressed (there is no face to score).

Configurable thresholds and actions

These warnings are scored and then mapped to a status through thresholds and actions you set per workflow:

Risk	Feature	Configurable behavior
`LOW_LIVENESS_SCORE`	`LIVENESS`	Score at or below the review threshold → `In Review`; at or below the decline threshold → `Declined`.
`LOW_FACE_MATCH_SIMILARITY`	`FACEMATCH`	Score at or below the review threshold (default 70) → `In Review`; at or below the decline threshold (default 50) → `Declined`.
`LOW_FACE_QUALITY`	`LIVENESS`	Review threshold (default 15) → `In Review`; decline threshold (default 0, i.e. decline disabled) → `Declined`. Passive Liveness only.
`LOW_FACE_LUMINANCE`	`LIVENESS`	Below the minimum luminance threshold (default 20): No action / Review (default) / Decline. Passive Liveness only.
`HIGH_FACE_LUMINANCE`	`LIVENESS`	Above the maximum luminance threshold (default 80): No action / Review (default) / Decline. Passive Liveness only.
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	No action (default) / Review / Decline when more than one face is captured. Passive Liveness only.
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	One shared duplicate-face action: No action (default) / Review / Decline for matches against other users’ approved or imported faces.

POSSIBLE_FACE_IN_BLOCKLIST (LIVENESS) is not configurable — a lower-confidence blocklist match is always routed to Review (log_type: "warning").

Capture retries

Failures driven only by fixable capture-quality risks (low score, no face, quality, luminance, multiple faces — and low similarity on face match) enter a retry loop before the status sticks: the user gets up to face_liveness_max_attempts / face_match_max_attempts total attempts (default 3, configurable 2–5 per workflow node). When the budget is exhausted, the last attempt’s computed status applies and LIVENESS_MAX_ATTEMPTS_EXCEEDED or FACE_MATCH_MAX_ATTEMPTS_EXCEEDED is logged as information to record it.

Liveness warnings

The API returns these exact short_description and long_description strings:

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	Low liveness score	The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.
`NO_FACE_DETECTED`	No Face Detected in liveness	The system couldn’t identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.
`LIVENESS_FACE_ATTACK`	Liveness Face Attack	The system detected a potential attempt to bypass the liveness check.
`FACE_IN_BLOCKLIST`	Face in blocklist	The system identified a face in the blocklist, which means the face is not allowed to be verified.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possible face in blocklist	The system identified a possible face in the blocklist, which means the face is not allowed to be verified.
`FACE_IN_ALLOWLIST`	Face in allowlist	The face matched the application’s face allowlist, so duplicate-face actions were skipped for this signal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Possible face in allowlist	The face possibly matched the application’s face allowlist, so possible duplicate-face actions were skipped for this signal.
`DUPLICATED_FACE`	Duplicated face from other approved session	The system identified a duplicated face from another approved session, requiring further investigation.
`POSSIBLE_DUPLICATED_FACE`	Possible duplicated face from other approved session	The system identified a possible duplicate face from another approved session, requiring further investigation.
`MULTIPLE_FACES_DETECTED` (Passive only)	Multiple faces detected	Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.
`LOW_FACE_QUALITY` (Passive only)	Low face quality	The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.
`LOW_FACE_LUMINANCE` (Passive only)	Low face luminance	The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.
`HIGH_FACE_LUMINANCE` (Passive only)	High face luminance	The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	Maximum liveness attempts exceeded	The maximum number of liveness capture attempts has been reached. The last attempt’s computed status (decline or review) has been applied.

Blocklist, allowlist, and duplicate matches carry additional_data with the matched session (blocklisted_session_id / allowlisted_session_id / duplicated_session_id, the matching *_session_number, and api_service). Only one of those six codes appears per report.

Face-match warnings

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	Low face match similarity	The facial features of the provided image don’t closely match the reference image, suggesting a potential identity mismatch.
`NO_REFERENCE_IMAGE`	No source image found for performing face match	A reference image for facial comparison is missing, preventing the system from completing the face matching process.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	Maximum face match attempts exceeded	The maximum number of face match capture attempts has been reached. The last attempt’s computed status (decline or review) has been applied.

Example — declined on face attack

{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}

Example — in review on low similarity

{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}

The score (58.70) sits between the decline threshold (default 50) and the review threshold (default 70), so the warning carries log_type: "warning" and the face-match status is In Review. In this example the warning fired on a session whose session_id is 11111111-2222-3333-4444-555555555555 — source_image_session_id carries the session’s own id because the reference came from the portrait stored at session creation.

Warning types

Each risk is assigned a warning type based on your application’s configuration. Warnings fall into three severity categories:

Biometric Auth report

Where liveness_checks[] and face_matches[] appear in the V3 decision.

Liveness warnings

Full liveness-warning reference including duplicate-face matching.

Face Match warnings

Full face-match warning reference for 1:1 comparisons.

​Overview

​Where warnings appear

​Automatic decline conditions

​Configurable thresholds and actions

​Capture retries

​Liveness warnings

​Face-match warnings

​Example — declined on face attack

​Example — in review on low similarity

​Warning types

​Related

Biometric Auth report

Liveness warnings

Face Match warnings

Overview

Where warnings appear

Automatic decline conditions

Configurable thresholds and actions

Capture retries

Liveness warnings

Face-match warnings

Example — declined on face attack

Example — in review on low similarity

Warning types

Related