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

# Поиск по лицу 1:N: предупреждения и коды ошибок

> Коды предупреждений Didit для поиска по лицу 1:N: совпадения со списком блокировки, дубликаты, несколько лиц и отклонение фото без лиц.

## Обзор

Поиск по лицу формирует небольшой набор предупреждений, позволяя вашей команде понять, **почему** поиск вернул `Approved` или `Declined`. Предупреждения возвращаются в массиве `face_search.warnings[]` ответа `POST /v3/face-search/` (см. [Отчёт Поиска по лицу](https://docs.didit.me/ru/core-technology/face-search/report-face-search.md)).

Предупреждения здесь имеют **сокращённую структуру** по сравнению с предупреждениями сценариев: в них отсутствует `node_id`. Документированный контракт ответа декларирует пять полей — `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, — а payload во время выполнения дополнительно содержит `feature`, которое на этом endpoint всегда имеет значение `"LIVENESS"`.

## Формируемые предупреждения

| Риск | Причина | Серьёзность (`log_type`) | Влияет на статус | Рекомендуемое действие |
| - | - | - | - | - |
| `FACE_IN_BLOCKLIST` | Изображение для поиска совпало с лицом из списка блокировки лиц вашего приложения в диапазоне высокой степени уверенности. | `error` | Принудительно устанавливает `Declined`. | Отклоните пользователя. Проверьте связанную сессию с помощью `additional_data.blocklisted_session_id`. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Лицо из списка блокировки совпало в нижнем диапазоне схожести «возможно», ниже диапазона высокой уверенности. | `error` | Принудительно устанавливает `Declined` в отдельном API Поиска по лицу (строже, чем проверка живости в сценарии, которая отправляет этот риск на проверку). | Ручная проверка. Подтвердите совпадение с исходными данными из списка блокировки перед принятием мер. |
| `MULTIPLE_FACES_DETECTED` | На переданном изображении для поиска обнаружено более одного лица. Поиск всё равно выполняется по самому крупному обнаруженному лицу. | `warning` | Нет — само по себе никогда не отклоняет. | Сделайте повторный снимок с одним человеком в кадре, если самое крупное лицо не является нужным. |
| `DUPLICATED_FACE` | Лицо совпало в диапазоне высокой уверенности с лицом из сессии со статусом **одобрена** или импортированным лицом из профиля пользователя. Отдельный endpoint не исключает сессии с одинаковым `vendor_data`, поэтому возвращающийся пользователь совпадает со своими собственными более ранними сессиями. | `information` | Нет — дубликаты выводятся как сигнал, а не как отклонения. | Проверьте связанную сессию с помощью `additional_data.duplicated_session_id`. Примите решение о блокировке или объединении аккаунтов на вашей стороне. |
| `POSSIBLE_DUPLICATED_FACE` | То же, что и `DUPLICATED_FACE`, но схожесть находится в нижнем диапазоне «возможно», а не в диапазоне высокой уверенности. | `information` | Нет. | Ручная проверка перед тем, как считать две записи одним и тем же человеком. |

Формирование: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); определение статуса: `get_face_search_status` (`apis/views/face_search.py:242-248`), отклоняющий запрос **только** при двух рисках, связанных со списком блокировки.

Правила формирования, о которых стоит знать:

* **Список блокировки имеет приоритет над дубликатами.** Подтверждённое совпадение со списком блокировки подавляет `DUPLICATED_FACE`, а возможное совпадение со списком блокировки подавляет `POSSIBLE_DUPLICATED_FACE` — вы никогда не получите оба элемента пары для одного и того же диапазона уверенности.
* **`additional_data` ссылается только на первое совпавшее лицо**, даже если `matches[]` содержит несколько. Предупреждения о списке блокировки содержат `{blocklisted_session_id, blocklisted_session_number, api_service}`; предупреждения о дубликатах содержат `{duplicated_session_id, duplicated_session_number, api_service}`; `MULTIPLE_FACES_DETECTED` содержит `null`. Значение `api_service` указывается в верхнем регистре (например, `PASSIVE_LIVENESS`) или равно `null` для сессий сценариев.
* **Лица из списка разрешений подавляют предупреждения о дубликатах** — совпадение со списком разрешений с высокой уверенностью снимает `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (оно никогда не снимает предупреждения о списке блокировки).

### Точные строки предупреждений

| Риск | `short_description` | `long_description` |
| - | - | - |
| `FACE_IN_BLOCKLIST` | Лицо в списке блокировки | Система обнаружила лицо в списке блокировки, что означает, что верификация данного лица запрещена. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Возможное лицо в списке блокировки | Система обнаружила возможное лицо в списке блокировки, что означает, что верификация данного лица запрещена. |
| `DUPLICATED_FACE` | Дубликат лица из другой одобренной сессии | Система обнаружила дубликат лица из другой одобренной сессии, что требует дополнительной проверки. |
| `POSSIBLE_DUPLICATED_FACE` | Возможный дубликат лица из другой одобренной сессии | Система обнаружила возможный дубликат лица из другой одобренной сессии, что требует дополнительной проверки. |
| `MULTIPLE_FACES_DETECTED` | Обнаружено несколько лиц | На изображении проверки живости обнаружено несколько лиц. Система использует самое крупное лицо для проверки живости и сравнения лиц, однако наличие нескольких лиц может потребовать дополнительной проверки. |

### Проверка изображения для поиска

Если в `user_image` не обнаружено ни одного лица, API отклоняет запрос с кодом HTTP `400` и `{"error": "No face detected in the image"}` **до** создания объекта `face_search` — поэтому предупреждение `NO_FACE_DETECTED` никогда не появляется в успешном ответе Поиска по лицу. Эта ошибка возвращается в виде строки `error` верхнего уровня, а не в `warnings[]`.

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

Диапазоны схожести, разделяющие подтверждённые совпадения (`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`) и возможные совпадения (`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`), зафиксированы внутри системы — настройка порогов для каждого приложения применяется к проверке живости в сценарии, а не к этому endpoint. Переключатели, которыми вы управляете для каждого запроса:

* **`search_type`** (`most_similar`, по умолчанию | `blocklisted_or_approved`) — `most_similar` ранжирует все зарегистрированные лица по схожести; `blocklisted_or_approved` ограничивает круг кандидатов лицами из списка блокировки, лицами из списка разрешений, лицами из одобренных сессий и импортированными лицами из профилей пользователей, ранжируя записи из списка блокировки первыми.
* **`save_api_request`** (по умолчанию `true`) — сохраняет вызов как сессию типа API и регистрирует искомое лицо в вашем индексе поиска по лицу. Лица, зарегистрированные при вызовах Поиска по лицу, исключаются из будущих результатов Поиска по лицу. Установите значение `false`, чтобы выполнить запрос без сохранения и регистрации.
* **`rotate_image`** (по умолчанию `false`) — пробует повороты на 90 градусов и сохраняет ориентацию с наилучшим обнаружением лица; полезно, если отсутствуют данные EXIF об ориентации.

## Примеры

### Совпадение со списком блокировки (приводит к `Declined`)

```json theme={null}
{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}
```

### Сигнал о дубликате (статус остаётся `Approved`)

```json theme={null}
{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Multiple faces detected",
      "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "api_service": null
      },
      "log_type": "information",
      "short_description": "Duplicated face from other approved session",
      "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
    }
  ]
}
```

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

* [Отчёт Face Search](https://docs.didit.me/ru/core-technology/face-search/report-face-search.md) — полная структура ответа
* [Справочник API Face Search](https://docs.didit.me/ru/standalone-apis/face-search.md) — параметры запроса
* [Предупреждения Face Match](https://docs.didit.me/ru/core-technology/id-verification/warnings-id-verification.md) — предупреждения при сравнении 1:1 селфи с документом (отдельно от Face Search)
* [Модели данных — Face Search](https://docs.didit.me/ru/reference/data-models.md#поиск-по-лицу) — каноническая схема

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


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