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

Обзор

Предупреждения в отчёте сравнения лиц фиксируют каждое условие, замеченное Didit при выполнении сравнения лиц 1:1. Они попадают в массив warnings[] для каждого элемента в face_matches[] (см. Отчёт сравнения лиц). Каждая запись также содержит feature: "FACEMATCH" и node_id узла сценария, который её вызвал. У каждого предупреждения есть три уровня:

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

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

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

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

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

При срабатывании NO_REFERENCE_IMAGE предупреждение LOW_FACE_MATCH_SIMILARITY подавляется (оценивать нечего). Существует одно исключение. Если шаг верификации личности был выполнен с помощью проверки без документов, реестр которой не возвращает портрет и не проверяет лицо, модулю Сравнение лиц конструктивно не с чем сравнивать живое селфи. В этом случае регистрируется 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 существует только порог отклонения (параметр запроса 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`	Оценка сходства не может быть рассчитана, поскольку лицо не обнаружено на портрете в документе или поскольку шаг верификации личности был проверкой без документа, которая не оставила эталонного изображения для сравнения (реестр, не возвращающий портрет и не проверяющий лицо). Подавляется, если также присутствует `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 — пограничное сходство

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

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

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

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

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

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

Отдельный API сравнения лиц возвращает предупреждения того же формата без поля node_id (сравнение не привязано к узлу сценария).

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

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

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

Отчет о сравнении лиц — полная схема отчета и статусы.
Предупреждения проверки живости — предшествующие предупреждения при захвате селфи.
Webhook’и — session.status.updated передает предупреждения сразу после завершения шага.
Модели данных — Сравнение лиц — каноническая схема.
Модели данных — Объект предупреждения — формат каждой записи в warnings[].

Аутентификация

Верификация

Мониторинг

Платформа

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

Обзор

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

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

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

Примеры

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

In Review — не удалось рассчитать оценку сходства

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

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

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

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

​Обзор

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

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

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

​Примеры

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

​In Review — не удалось рассчитать оценку сходства

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

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

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

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

Обзор

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

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

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

Примеры

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

In Review — не удалось рассчитать оценку сходства

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

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

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

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