Face match warnings

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:

The risk code — a stable identifier you can match on in your code.
The log_type — information, warning, or error, derived from your workflow’s similarity-score thresholds.
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).

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 because no face was detected in one of the images:

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 both FACE_MATCH_NOT_COMPUTED (no face in the document portrait) 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 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. 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.
`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.	`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

"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

"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

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

Face match report — full report schema and statuses.
Liveness warnings — upstream warnings on the selfie capture.
Webhooks — session.status.updated carries the warnings as soon as the step finishes.
Data models — Face match — canonical schema.
Data models — Warning object — the shape of every entry in warnings[].

Authentication

Verification

Monitoring

Platform

Overview

Auto-decline conditions

Configurable verification settings

Warnings produced

Examples

In Review — borderline similarity

In Review — face match could not be computed

Auto-decline — missing reference

Retries exhausted — last attempt’s status applied

Warning types

​Overview

​Auto-decline conditions

​Configurable verification settings

​Warnings produced

​Examples

​In Review — borderline similarity

​In Review — face match could not be computed

​Auto-decline — missing reference

​Retries exhausted — last attempt’s status applied

​Warning types

​Related

Overview

Auto-decline conditions

Configurable verification settings

Warnings produced

Examples

In Review — borderline similarity

In Review — face match could not be computed

Auto-decline — missing reference

Retries exhausted — last attempt’s status applied

Warning types

Related