> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Biometric Authentication Warnings > Handle biometric auth warnings: LOW_LIVENESS_SCORE, face attacks, blocklist matches, and low face-match similarity. Configure thresholds and decline actions. export const WarningTypes = () =>
{WARNING_TYPES.map(w =>
{w.icon}
{w.type}
{w.description}
)}
; 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](/reference/data-models#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 ```json theme={null} { "liveness_checks": [ { "node_id": "feature_liveness", "status": "Declined", "method": "ACTIVE_3D", "score": 12.40, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../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 ```json theme={null} { "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:///.../source.jpg", "target_image": "https:///.../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: ## Related Where `liveness_checks[]` and `face_matches[]` appear in the V3 decision. Full liveness-warning reference including duplicate-face matching. Full face-match warning reference for 1:1 comparisons.