> ## 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 = () => <div style={{
  display: "flex",
  flexDirection: "column",
  gap: "12px",
  margin: "16px 0"
}}>
    {WARNING_TYPES.map(w => <div key={w.type} style={{
  display: "flex",
  alignItems: "flex-start",
  gap: "12px",
  padding: "12px 16px",
  borderRadius: "8px",
  background: w.bg
}}>
        <span style={{
  fontSize: "16px",
  lineHeight: "24px"
}}>{w.icon}</span>
        <div>
          <div style={{
  fontWeight: 600,
  color: w.color,
  marginBottom: "2px"
}}>
            <code style={{
  background: "transparent",
  color: w.color,
  fontWeight: 600,
  padding: 0
}}>
              {w.type}
            </code>
          </div>
          <div style={{
  fontSize: "14px",
  lineHeight: "20px",
  color: "#374151"
}}>
            {w.description}
          </div>
        </div>
      </div>)}
  </div>;

## 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 three 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.

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](/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.                                                                               |
| `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

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

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

<Note>
  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).
</Note>

## Warning types

Each risk is assigned a severity based on your application's configuration. The three severities are:

<WarningTypes />

## 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[]`.