Skip to main content

​
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). 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 three risk codes, listed in full below.

​
Auto-decline conditions

The following risk always forces the face match report (and the session) to Declined:
RiskTrigger
NO_REFERENCE_IMAGEOne 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).

​
Configurable verification settings

In the Didit console, the face match similarity score is governed by two thresholds (no Approve/Review/Decline toggle):
SettingDefaultBehavior
face_match_score_review_threshold70When score ≤ this value, LOW_FACE_MATCH_SIMILARITY fires and the status moves to In Review.
face_match_score_decline_threshold50When 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. 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. 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 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

RiskCauseSeverityAffects status?Remediation
LOW_FACE_MATCH_SIMILARITYscore ≤ face_match_score_review_threshold. Suppressed when NO_REFERENCE_IMAGE is also present.warning between the thresholds; error at or below the decline thresholdIn Review between the thresholds; Declined at or below the decline thresholdTune thresholds, or accept via manual review.
NO_REFERENCE_IMAGEEither the reference image or the target image is missing.errorAuto-declineEnsure both the document portrait and the liveness selfie are captured. For the standalone API, pass two valid face images.
FACE_MATCH_MAX_ATTEMPTS_EXCEEDEDThe user exhausted the capture-retry budget (face_match_max_attempts) after repeated low-similarity failures.informationNo — records that the last attempt’s computed status (decline or review) was appliedRaise face_match_max_attempts on the workflow node, or resolve via manual review.

​
Examples

​
In Review — borderline similarity

"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"
  }
]

​
Auto-decline — missing reference

"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

"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 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: