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

# Сравнение лиц: предупреждения и коды ошибок

> Все предупреждения Didit при сравнении лиц 1:1: причины, критичность и решение при низкой схожести, отсутствии фото и исчерпании попыток.

## Обзор

Предупреждения в отчёте сравнения лиц фиксируют каждое условие, замеченное Didit при выполнении сравнения лиц 1:1. Они попадают в массив `warnings[]` для каждого элемента в `face_matches[]` (см. [Отчёт сравнения лиц](https://docs.didit.me/ru/core-technology/face-match/report-face-match.md)). Каждая запись также содержит `feature: "FACEMATCH"` и `node_id` узла сценария, который её вызвал.

У каждого предупреждения есть три уровня:

1. **Код `risk`** — постоянный идентификатор, по которому можно ориентироваться в коде.
2. **`log_type`** — `information`, `warning` или `error`, определяемый на основе пороговых значений оценки сходства в вашем сценарии.
3. **Влияние на решение** — задаётся порогами проверки и отклонения для оценки сходства в сценарии.

Модуль сравнения лиц намеренно компактен — существует ровно пять кодов риска, полный список которых приведён ниже.

## Условия автоматического отклонения

Следующий риск всегда переводит отчёт сравнения лиц (и сессию) в статус `Declined`:

| Риск | Триггер |
| - | - |
| `NO_REFERENCE_IMAGE` | Отсутствует одно из изображений: `source_image` (эталон) или `target_image` (селфи), поэтому сравнение оказалось невозможным. |

При срабатывании `NO_REFERENCE_IMAGE` предупреждение `LOW_FACE_MATCH_SIMILARITY` подавляется (оценивать нечего).

Существует одно исключение.
Если шаг верификации личности был выполнен с помощью [проверки без документов](https://docs.didit.me/ru/core-technology/id-verification/non-doc-lookup.md), реестр которой не возвращает портрет и не проверяет лицо, модулю Сравнение лиц конструктивно не с чем сравнивать живое селфи.
В этом случае регистрируется `FACE_MATCH_NOT_COMPUTED` с оценкой `null`, а решение принимается параметром `face_match_not_computed_action` (см. ниже), а не через автоматическое отклонение.

## Настраиваемые параметры верификации

В консоли Didit оценка сходства лиц регулируется двумя порогами (без переключателя Одобрить/На проверку/Отклонить):

| Настройка | По умолчанию | Поведение |
| - | - | - |
| `face_match_score_review_threshold` | 70 | Если `score` ≤ этого значения, срабатывает `LOW_FACE_MATCH_SIMILARITY`, и статус меняется на `In Review`. |
| `face_match_score_decline_threshold` | 50 | Если `score` ≤ этого значения, это же предупреждение переходит в уровень `error`, и статус меняется на `Declined`. |

Увеличьте порог отправки на проверку, если вы сталкиваетесь со слишком большим числом ложных одобрений; уменьшите порог отклонения, если наблюдается слишком много ложных отклонений.

Отдельная настройка определяет, что происходит, когда оценку сходства **вообще невозможно рассчитать**: на одном из изображений не обнаружено лицо, либо проверка без документов не оставила эталонного изображения для сравнения:

| Настройка | По умолчанию | Поведение |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | Действие, применяемое, когда результат "не удалось рассчитать" становится окончательным. При `REVIEW` отчёт отправляется `In Review`; при `DECLINE` получает статус `Declined`. (Варианта автоматического одобрения нет — результат, который так и не был рассчитан, никогда не одобряется автоматически.) |

Это действие управляет `FACE_MATCH_NOT_COMPUTED` (нет лица на портрете в документе или эталон полностью отсутствует после проверки без документов) и случаем исчерпания попыток при `NO_FACE_IN_SELFIE` (лицо на селфи так и не найдено после повторных попыток пользователя). Если проблема заключается в селфи, пользователю сначала предлагается переснять его — см. ниже, — а действие применяется только в том случае, если лицо по-прежнему не удаётся обнаружить после исчерпания лимита попыток.

Неудачи из-за низкой оценки сходства также переходят в цикл повторных съёмок, прежде чем статус зафиксируется: пользователю даётся суммарно до `face_match_max_attempts` попыток (по умолчанию 3, настраивается от 2 до 5 на узел сценария) для повторного фото. Ошибка `NO_FACE_IN_SELFIE` использует тот же цикл повторных попыток, поскольку более чёткое повторное селфи может решить проблему. Ошибка `FACE_MATCH_NOT_COMPUTED` **не** даёт повторных попыток — портрет из документа нельзя переснять на этом шаге. Только когда лимит исчерпан, применяется статус последней попытки — и в журнал записывается `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` для фиксации события.

В отдельном [Face Match API](https://docs.didit.me/ru/standalone-apis/face-match.md) существует только порог отклонения (параметр запроса `face_match_score_decline_threshold`, по умолчанию 30); любое сработавшее предупреждение отклоняет запрос, а `NO_REFERENCE_IMAGE` срабатывает, когда лицо вообще не удалось сравнить.

## Создаваемые предупреждения

| Риск | Причина | Уровень критичности | Влияет на статус? | Устранение |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. Подавляется, если также присутствует `NO_REFERENCE_IMAGE`. | `warning` в диапазоне между порогами; `error` на уровне или ниже порога отклонения | `In Review` в диапазоне между порогами; `Declined` на уровне или ниже порога отклонения | Настройте пороги или одобрите через ручную проверку. |
| `FACE_MATCH_NOT_COMPUTED` | Оценка сходства не может быть рассчитана, поскольку лицо не обнаружено на **портрете в документе** или поскольку шаг верификации личности был [проверкой без документа](https://docs.didit.me/ru/core-technology/id-verification/non-doc-lookup.md), которая не оставила эталонного изображения для сравнения (реестр, не возвращающий портрет и не проверяющий лицо). Подавляется, если также присутствует `NO_REFERENCE_IMAGE`. | `warning`, когда `face_match_not_computed_action` установлено в `REVIEW`; `error`, когда `DECLINE` | `In Review` или `Declined` в соответствии с `face_match_not_computed_action` | Изображение документа невозможно захватить повторно на этом шаге: решите проблему через ручную проверку или запросите повторный захват документа ранее в сценарии. После проверки только по данным задайте для `face_match_not_computed_action` желаемый результат или требуйте документ в странах, где биометрическое совпадение имеет значение. |
| `NO_FACE_IN_SELFIE` | Оценка сходства не может быть рассчитана, поскольку лицо не обнаружено на **селфи** пользователя. Пользователю предлагается переснять селфи, прежде чем это предупреждение зафиксируется. | `warning`, когда `face_match_not_computed_action` установлено в `REVIEW`; `error`, когда `DECLINE` | `In Review` или `Declined` в соответствии с `face_match_not_computed_action`, после исчерпания повторных попыток | Пользователь повторно делает более четкое фронтальное селфи с хорошим освещением. |
| `NO_REFERENCE_IMAGE` | Отсутствует либо эталонное изображение, либо целевое изображение (за исключением эталона, который никогда не создавался проверкой без документа, что соответствует `FACE_MATCH_NOT_COMPUTED`). | `error` | **Автоматическое отклонение** | Убедитесь, что захвачены и портрет из документа, и селфи для проверки живости. Для отдельного API передайте два корректных изображения лиц. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | Пользователь исчерпал лимит повторных попыток захвата (`face_match_max_attempts`) после неоднократных неудач из-за низкого сходства. | `information` | Нет — фиксирует, что был применен рассчитанный статус последней попытки (отклонение или проверка) | Увеличьте `face_match_max_attempts` в узле сценария или решите проблему через ручную проверку. |

## Примеры

### In Review — пограничное сходство

```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 — не удалось рассчитать оценку сходства

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

### Автоматическое отклонение — отсутствует эталонное изображение

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

### Повторные попытки исчерпаны — применен статус последней попытки

```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]
>
> Отдельный [API сравнения лиц](https://docs.didit.me/ru/standalone-apis/face-match.md) возвращает предупреждения того же формата без поля `node_id` (сравнение не привязано к узлу сценария).

## Типы предупреждений

Каждому риску присваивается уровень критичности в зависимости от конфигурации вашего приложения. Существует три уровня критичности:

## Связанные материалы

* [Отчет о сравнении лиц](https://docs.didit.me/ru/core-technology/face-match/report-face-match.md) — полная схема отчета и статусы.
* [Предупреждения проверки живости](https://docs.didit.me/ru/core-technology/liveness/warnings-liveness.md) — предшествующие предупреждения при захвате селфи.
* [Webhook'и](https://docs.didit.me/ru/integration/webhooks.md) — `session.status.updated` передает предупреждения сразу после завершения шага.
* [Модели данных — Сравнение лиц](https://docs.didit.me/ru/reference/data-models.md#сравнение-лиц) — каноническая схема.
* [Модели данных — Объект предупреждения](https://docs.didit.me/ru/reference/data-models.md#объект-предупреждения) — формат каждой записи в `warnings[]`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.