> ## 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. # Liveness warnings > Every warning Didit's liveness module emits — face attacks, low-score and quality triggers, blocklist matches, duplicate faces — with cause and remediation. export const WarningTypes = () =>
{WARNING_TYPES.map(w =>
{w.icon}
{w.type}
{w.description}
)}
; ## Overview Warnings on the liveness report flag every condition Didit observed while running the liveness check. They land in the `warnings[]` array on each item of `liveness_checks[]` (see [Liveness report](/core-technology/liveness/report-liveness)), with `feature` set to `"LIVENESS"`. Each entry follows the shared [warning object](/reference/data-models#warning-object) shape: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`. Every warning has three layers: 1. **The `risk` code** — a stable identifier you can match on in your code (the codes listed below). 2. **The `log_type`** — one of `information`, `warning`, or `error`. Auto-decline risks always carry `error`. For configurable risks it is derived from the configured action: **No action** → `information`, **Review** → `warning`, **Decline** → `error`. For threshold-driven risks (`LOW_LIVENESS_SCORE`, `LOW_FACE_QUALITY`) it is `error` when the value crosses the decline threshold and `warning` when it only crosses the review threshold. 3. **The decision impact** — the same routing drives the liveness report's `status`: a Review action moves it to `In Review`, a Decline action (or any auto-decline risk) to `Declined`, and No action leaves it untouched. Some risks are emitted only when the liveness method is `PASSIVE` (multiple-faces, quality, and luminance checks). The tables below list the full set of liveness risk codes and their severities — no other liveness risk codes exist. ## Auto-decline conditions The following risks always force the liveness report (and the session) to `Declined`, with `log_type: "error"`: | Risk | Trigger | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `NO_FACE_DETECTED` | No face was located during the liveness capture, or the user exhausted retry attempts. | | `LIVENESS_FACE_ATTACK` | The model detected a presentation attack (mask, screen replay, deepfake-class spoof). | | `FACE_IN_BLOCKLIST` | The face matched an entry on your application's face blocklist. | | `AGE_BELOW_MINIMUM` | Estimated age below the configured minimum. Only emitted on adaptive age-verification workflows and `AGE_ESTIMATION` nodes. | | `AGE_NOT_DETECTED` | Age could not be estimated. Only emitted on age-estimation flows with ID-verification fallback disabled. | When `NO_FACE_DETECTED` fires, `LOW_LIVENESS_SCORE` is suppressed (there is no face to score). ## Configurable verification settings In the Didit console, liveness risks are grouped under the following workflow settings: | Group | Risks | Configuration | | ----------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Liveness score thresholds** | `LOW_LIVENESS_SCORE` | Review threshold + decline threshold on `score`. At or below review → `In Review`; at or below decline → `Declined`. | | **Duplicate face action** | `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` | One shared setting: No action (default) / Review / Decline. Skipped entirely when the matching face is in your face allowlist. | | **Possible blocklisted face** | `POSSIBLE_FACE_IN_BLOCKLIST` | Not configurable in workflows — always routed to Review (`log_type: "warning"`). | | **Multiple faces action** *(passive only)* | `MULTIPLE_FACES_DETECTED` | No action (default) / Review / Decline. | | **Face quality thresholds** *(passive only)* | `LOW_FACE_QUALITY` | Review threshold (default 15) + decline threshold (default 0, i.e. decline disabled). | | **Face luminance** *(passive only)* | `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE` | Min / max thresholds (defaults 20 / 80 on the normalized 0–100 scale) + a per-direction action (default Review). | | **Age thresholds** *(adaptive workflows / `AGE_ESTIMATION` node)* | `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED` | Minimum and borderline age thresholds; both risks auto-decline the liveness step. With ID-verification fallback enabled, the workflow routes the user to a document check instead of ending the session. | ## Warnings produced ### Core liveness | Risk | Cause | Severity | Affects status? | Remediation | | ---------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------- | | `NO_FACE_DETECTED` | No face located during the capture, or the user exhausted retry attempts (`MAX_ATTEMPTS_REACHED`). | `error` | **Auto-decline** | Re-capture in better lighting; ensure the face is centered. | | `LIVENESS_FACE_ATTACK` | Model detected a presentation attack. | `error` | **Auto-decline** | Treat as fraud. The session is automatically declined. | | `LOW_LIVENESS_SCORE` | `score` at or below the workflow's review threshold. Suppressed when `NO_FACE_DETECTED` is also present. | `warning`; escalates to `error` when the score is at or below the decline threshold | Configurable (review / decline thresholds) | Re-capture; tune thresholds if you observe false positives. | ### Cross-session face matching | Risk | Cause | Additional data | Severity | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------ | | `FACE_IN_BLOCKLIST` | Face matched a blocklisted face. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `error` — **auto-decline** | | `POSSIBLE_FACE_IN_BLOCKLIST` | Face matched a blocklisted face at a lower-confidence band. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `warning` — always routed to Review in workflows | | `FACE_IN_ALLOWLIST` | Face matched an allowlisted face. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — duplicate-face action skipped | | `POSSIBLE_FACE_IN_ALLOWLIST` | Face matched an allowlisted face at a lower-confidence band. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — possible duplicate-face action skipped | | `DUPLICATED_FACE` | Face matched an already-approved face from another user (an `Approved` session with different `vendor_data`, or a face imported against one of your vendor users). | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Configurable — `information` by default | | `POSSIBLE_DUPLICATED_FACE` | Face matched another approved or imported face at a lower-confidence band. | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Configurable — `information` by default | For matches against imported faces or list-entry faces (which have no session), the `*_session_id`, `*_session_number`, and `api_service` values in `additional_data` are `null`. Faces belonging to the same user (same `vendor_data`, or the same vendor user when available) are excluded from the **entire** index search — both duplicate detection and blocklist screening. Match precedence is: blocklist exact → allowlist exact → duplicate exact → blocklist possible → allowlist possible → duplicate possible — only one of these six codes appears per report. ### Passive liveness quality (only when `method = "PASSIVE"`) | Risk | Cause | Severity | Remediation | | ------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------- | | `MULTIPLE_FACES_DETECTED` | More than one face was visible during the capture. The largest face is always used for scoring and matching. | Configurable — `information` by default | Recapture solo. | | `LOW_FACE_QUALITY` | Face quality below the review threshold (default 15). | `warning`; `error` when below the decline threshold (default 0 — decline disabled) | Better focus / less occlusion / centered face. | | `LOW_FACE_LUMINANCE` | Normalized luminance below the minimum threshold (default 20). | Configurable — `warning` by default (action defaults to Review) | Better lighting. | | `HIGH_FACE_LUMINANCE` | Normalized luminance above the maximum threshold (default 80). | Configurable — `warning` by default (action defaults to Review) | Reduce lighting; avoid backlight. | `LOW_FACE_LUMINANCE` and `HIGH_FACE_LUMINANCE` are mutually exclusive — the luminance is either below the minimum or above the maximum, never both. ### Age estimation (adaptive workflows and `AGE_ESTIMATION` nodes) | Risk | Cause | Severity | Remediation | | ------------------- | -------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------- | | `AGE_BELOW_MINIMUM` | Estimated age below the configured minimum (or borderline threshold when ID-verification fallback is enabled). | `error` | Workflow falls back to ID verification when configured. | | `AGE_NOT_DETECTED` | Age could not be estimated and ID-verification fallback is disabled. | `error` | Enable fallback or re-capture. | ## Exact description strings The API returns these exact `short_description` and `long_description` strings for each risk: | `risk` | `short_description` | `long_description` | | ---------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | | `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. | | `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` | 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` | 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` | 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` | 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. | | `AGE_BELOW_MINIMUM` | Age below minimum | The age of the face is below the minimum age threshold for the application. | | `AGE_NOT_DETECTED` | Age not detected | The system couldn't identify the age of the face, which is necessary for document verification. | ## Standalone passive liveness API The standalone [Liveness API](/standalone-apis/passive-liveness) reuses the same risk codes with a few behavioral differences: * `NO_FACE_DETECTED` and `LOW_LIVENESS_SCORE` are mutually exclusive — the score check only runs when a face was found. `LOW_LIVENESS_SCORE` fires against the request's `face_liveness_score_decline_threshold` (default 30) and always carries `log_type: "error"`. * `POSSIBLE_FACE_IN_BLOCKLIST` is treated as a decline (`log_type: "error"`) instead of review. * `MULTIPLE_FACES_DETECTED` carries `log_type: "warning"`, while the duplicate-face risks stay informational. Only `error`-level warnings flip the standalone response's `status` to `Declined`. * Standalone warning entries include `feature` but no `node_id`. ## Examples ### Auto-decline on detected attack ```json theme={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": "liveness_primary" } ] ``` ### Configurable warnings on a passive capture ```json theme={null} "warnings": [ { "feature": "LIVENESS", "risk": "LOW_FACE_QUALITY", "additional_data": null, "log_type": "warning", "short_description": "Low face quality", "long_description": "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.", "node_id": "liveness_primary" }, { "feature": "LIVENESS", "risk": "LOW_FACE_LUMINANCE", "additional_data": null, "log_type": "warning", "short_description": "Low face luminance", "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.", "node_id": "liveness_primary" }, { "feature": "LIVENESS", "risk": "MULTIPLE_FACES_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Multiple faces detected", "long_description": "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.", "node_id": "liveness_primary" } ] ``` ### Duplicate face with payload ```json theme={null} "warnings": [ { "feature": "LIVENESS", "risk": "DUPLICATED_FACE", "additional_data": { "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f", "duplicated_session_number": 123, "api_service": null }, "log_type": "warning", "short_description": "Duplicated face from other approved session", "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.", "node_id": "liveness_primary" } ] ``` Here the duplicate-face action is set to Review, so the warning carries `log_type: "warning"` and the liveness report's status is `In Review`. With the default (No action) it would carry `log_type: "information"` instead. `api_service` is `null` because the matched face came from a workflow session, not a standalone API call. ## Warning types Each risk is assigned a severity based on your application's configuration. The three severities are: ## Related * [Liveness report](/core-technology/liveness/report-liveness) — full report schema and statuses. * [Face match warnings](/core-technology/face-match/warnings-face-match) — companion 1:1 face match warnings. * [Webhooks](/integration/webhooks) — `session.status.updated` carries the warnings as soon as the liveness step finishes. * [Data models — Liveness check](/reference/data-models#liveness-check) — canonical schema with every field. * [Data models — Warning object](/reference/data-models#warning-object) — the shape of every entry in `warnings[]`.