> ## 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. # Face match warnings > Every warning Didit's face match 1:1 module emits — low similarity, missing reference image, exhausted retries — with cause, severity, and remediation. export const WarningTypes = () =>
{WARNING_TYPES.map(w =>
{w.icon}
{w.type}
{w.description}
)}
; ## Overview Warnings on the face match report flag every condition Didit observed while running the 1:1 face comparison. They land in the `warnings[]` array on each item of `face_matches[]` (see [Face match report](/core-technology/face-match/report-face-match)). Each entry also carries `feature: "FACEMATCH"` and the `node_id` of the workflow node that raised it. Every warning has three layers: 1. **The `risk` code** — a stable identifier you can match on in your code. 2. **The `log_type`** — `information`, `warning`, or `error`, derived from your workflow's similarity-score thresholds. 3. **The decision impact** — set by the workflow's review and decline thresholds for the similarity score. The face match module is intentionally small — there are exactly five risk codes, listed in full below. ## Auto-decline conditions The following risk always forces the face match report (and the session) to `Declined`: | Risk | Trigger | | - | - | | `NO_REFERENCE_IMAGE` | One of `source_image` (reference) or `target_image` (selfie) is missing, so no comparison was possible. | When `NO_REFERENCE_IMAGE` fires, `LOW_FACE_MATCH_SIMILARITY` is suppressed (there is nothing to score). There is one exception. When the ID step was completed by a [non-doc lookup](/core-technology/id-verification/non-doc-lookup) whose register returns no portrait and checks no face, Face Match has nothing to compare the live capture against by design. That is reported as `FACE_MATCH_NOT_COMPUTED` with a `null` score and decided by `face_match_not_computed_action` (below), not as an automatic decline. ## Configurable verification settings In the Didit console, the face match similarity score is governed by two thresholds (no Approve/Review/Decline toggle): | Setting | Default | Behavior | | - | - | - | | `face_match_score_review_threshold` | 70 | When `score` ≤ this value, `LOW_FACE_MATCH_SIMILARITY` fires and the status moves to `In Review`. | | `face_match_score_decline_threshold` | 50 | When `score` ≤ this value, the same warning escalates to `error` and the status moves to `Declined`. | Tune the review threshold higher if you observe too many false approvals; tune the decline threshold lower if you observe too many false declines. A separate setting controls what happens when a similarity score **cannot be computed at all**: no face was detected in one of the images, or a non-doc lookup left no reference to compare against: | Setting | Default | Behavior | | - | - | - | | `face_match_not_computed_action` | `REVIEW` | Action applied once the "could not compute" outcome is terminal. `REVIEW` sends the report to `In Review`; `DECLINE` sets it to `Declined`. (There is no auto-approve option — a score that was never computed is never silently passed.) | This action governs `FACE_MATCH_NOT_COMPUTED` (no face in the document portrait, or no reference at all after a non-doc lookup) and an exhausted `NO_FACE_IN_SELFIE` (no face in the selfie after the user's retries). When the selfie is the problem, the user is first asked to recapture — see below — and the action only applies if a face still cannot be detected once the attempt budget runs out. Low-similarity failures also enter a capture-retry loop before the status sticks: the user gets up to `face_match_max_attempts` total attempts (default 3, configurable 2–5 per workflow node) to recapture. A `NO_FACE_IN_SELFIE` failure uses the same retry loop, since recapturing a clearer selfie can fix it. A `FACE_MATCH_NOT_COMPUTED` failure does **not** retry — the document portrait cannot be recaptured at this step. Only when the budget is exhausted does the last attempt's status apply — and `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` is logged to record it. On the standalone [Face Match API](/standalone-apis/face-match) only a decline threshold exists (`face_match_score_decline_threshold` request option, default 30); any fired warning declines the request, and `NO_REFERENCE_IMAGE` fires when no face could be compared at all. ## Warnings produced | Risk | Cause | Severity | Affects status? | Remediation | | - | - | - | - | - | | `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. Suppressed when `NO_REFERENCE_IMAGE` is also present. | `warning` between the thresholds; `error` at or below the decline threshold | `In Review` between the thresholds; `Declined` at or below the decline threshold | Tune thresholds, or accept via manual review. | | `FACE_MATCH_NOT_COMPUTED` | A similarity score could not be computed because no face was detected in the **document portrait**, or because the ID step was a [non-doc lookup](/core-technology/id-verification/non-doc-lookup) that left no reference to compare against (a register that returns no portrait and checks no face). Suppressed when `NO_REFERENCE_IMAGE` is also present. | `warning` when `face_match_not_computed_action` is `REVIEW`; `error` when `DECLINE` | `In Review` or `Declined`, per `face_match_not_computed_action` | The document image cannot be recaptured at this step: resolve via manual review, or recapture the document earlier in the flow. After a data-only lookup, set `face_match_not_computed_action` to the outcome you want, or require a document in countries where a biometric match matters. | | `NO_FACE_IN_SELFIE` | A similarity score could not be computed because no face was detected in the user's **selfie**. The user is asked to retake the selfie before this sticks. | `warning` when `face_match_not_computed_action` is `REVIEW`; `error` when `DECLINE` | `In Review` or `Declined`, per `face_match_not_computed_action`, after retries are exhausted | The user recaptures a clearer, well-lit, front-facing selfie. | | `NO_REFERENCE_IMAGE` | Either the reference image or the target image is missing (except a reference that a non-doc lookup never produced, which is `FACE_MATCH_NOT_COMPUTED`). | `error` | **Auto-decline** | Ensure both the document portrait and the liveness selfie are captured. For the standalone API, pass two valid face images. | | `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | The user exhausted the capture-retry budget (`face_match_max_attempts`) after repeated low-similarity failures. | `information` | No — records that the last attempt's computed status (decline or review) was applied | Raise `face_match_max_attempts` on the workflow node, or resolve via manual review. | ## Examples ### In Review — borderline similarity ```json theme={null} "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_1" } ] ``` ### In Review — face match could not be computed ```json theme={null} "warnings": [ { "feature": "FACEMATCH", "risk": "FACE_MATCH_NOT_COMPUTED", "additional_data": null, "log_type": "warning", "short_description": "Face match could not be computed", "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.", "node_id": "feature_face_match_1" } ] ``` ### Auto-decline — missing reference ```json theme={null} "warnings": [ { "feature": "FACEMATCH", "risk": "NO_REFERENCE_IMAGE", "additional_data": null, "log_type": "error", "short_description": "No source image found for performing face match", "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.", "node_id": "feature_face_match_1" } ] ``` ### Retries exhausted — last attempt's status applied ```json theme={null} "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "error", "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_1" }, { "feature": "FACEMATCH", "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED", "additional_data": null, "log_type": "information", "short_description": "Maximum face match attempts exceeded", "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.", "node_id": "feature_face_match_1" } ] ``` The standalone [Face Match API](/standalone-apis/face-match) returns the same warning shape minus `node_id` (the comparison is not bound to a workflow node). ## Warning types Each risk is assigned a severity based on your application's configuration. The three severities are: ## Related * [Face match report](/core-technology/face-match/report-face-match) — full report schema and statuses. * [Liveness warnings](/core-technology/liveness/warnings-liveness) — upstream warnings on the selfie capture. * [Webhooks](/integration/webhooks) — `session.status.updated` carries the warnings as soon as the step finishes. * [Data models — Face match](/reference/data-models#face-match) — canonical schema. * [Data models — Warning object](/reference/data-models#warning-object) — the shape of every entry in `warnings[]`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.