> ## 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 search warnings > Reference for Face Search 1:N warning codes: blocklist matches, duplicate faces, multiple faces, and the search-image gate that rejects images with no detectable face. export const WarningTypes = () =>
{WARNING_TYPES.map(w =>
{w.icon}
{w.type}
{w.description}
)}
; ## Overview Face Search emits a small set of warnings so your team can tell **why** a search returned `Approved` or `Declined`. Warnings are returned in the `face_search.warnings[]` array of the `POST /v3/face-search/` response (see [Face Search report](/core-technology/face-search/report-face-search)). Warnings here use a **reduced shape** compared with workflow warnings: there is no `node_id`. The documented response contract declares five fields — `risk`, `additional_data`, `log_type`, `short_description`, `long_description` — and the runtime payload additionally carries `feature`, which is always `"LIVENESS"` on this endpoint. ## Warnings produced | Risk | Cause | Severity (`log_type`) | Affects status | Recommended remediation | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `FACE_IN_BLOCKLIST` | The search image matched a face in your application's face blocklist above the high-confidence similarity band. | `error` | Forces `Declined`. | Reject the user. Investigate the linked session via `additional_data.blocklisted_session_id`. | | `POSSIBLE_FACE_IN_BLOCKLIST` | A blocklisted face matched within the lower "possible" similarity band, below the high-confidence band. | `error` | Forces `Declined` on the standalone Face Search API (stricter than the workflow liveness check, which sends this risk to review). | Manual review. Confirm the hit against the original blocklist evidence before acting. | | `MULTIPLE_FACES_DETECTED` | More than one face was found in the submitted search image. The search still runs, using the largest detected face. | `warning` | None — never declines on its own. | Re-capture with a single subject in frame if the largest face is not the intended one. | | `DUPLICATED_FACE` | The face matched, above the high-confidence band, a face from an **approved** session or an imported user-profile face. The standalone endpoint does not exclude same-`vendor_data` sessions, so a returning user matches their own earlier sessions. | `information` | None — duplicates are surfaced as signal, not declines. | Investigate the linked session via `additional_data.duplicated_session_id`. Decide whether to block or merge accounts on your side. | | `POSSIBLE_DUPLICATED_FACE` | Same as `DUPLICATED_FACE` but the similarity sits in the lower "possible" band rather than the high-confidence band. | `information` | None. | Manual review before treating the two records as the same person. | Producer: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); status derivation: `get_face_search_status` (`apis/views/face_search.py:242-248`), which declines **only** for the two blocklist risks. Emission rules worth knowing: * **Blocklist takes precedence over duplicates.** A confirmed blocklist hit suppresses `DUPLICATED_FACE`, and a possible blocklist hit suppresses `POSSIBLE_DUPLICATED_FACE` — you never get both members of a pair for the same confidence band. * **`additional_data` references the first matching face only**, even when `matches[]` contains several. Blocklist warnings carry `{blocklisted_session_id, blocklisted_session_number, api_service}`; duplicate warnings carry `{duplicated_session_id, duplicated_session_number, api_service}`; `MULTIPLE_FACES_DETECTED` carries `null`. The `api_service` value is uppercase (e.g. `PASSIVE_LIVENESS`) or `null` for workflow sessions. * **Allowlisted faces suppress duplicate warnings** — a high-confidence allowlist match clears `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (it never clears blocklist warnings). ### Exact warning strings | Risk | `short_description` | `long_description` | | ---------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `FACE_IN_BLOCKLIST` | Face in blocklist | The system identified a face in the blocklist, which means the face is not allowed to be verified. | | `POSSIBLE_FACE_IN_BLOCKLIST` | Possible face in blocklist | The system identified a possible face in the blocklist, which means the face is not allowed to be verified. | | `DUPLICATED_FACE` | Duplicated face from other approved session | The system identified a duplicated face from another approved session, requiring further investigation. | | `POSSIBLE_DUPLICATED_FACE` | Possible duplicated face from other approved session | The system identified a possible duplicate face from another approved session, requiring further investigation. | | `MULTIPLE_FACES_DETECTED` | Multiple faces detected | 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. | ### Search-image gate When no face is detected in `user_image`, the API rejects the request with HTTP `400` and `{"error": "No face detected in the image"}` **before** a `face_search` object is built — so a `NO_FACE_DETECTED` warning never appears in a successful Face Search response. This is returned as a top-level `error` string, not in `warnings[]`. ## Configurable settings The similarity bands that split confirmed hits (`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`) from possible hits (`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`) are fixed internally — per-application threshold tuning applies to the workflow liveness check, not this endpoint. The switches you control per request are: * **`search_type`** (`most_similar`, default | `blocklisted_or_approved`) — `most_similar` ranks every enrolled face by similarity; `blocklisted_or_approved` restricts candidates to blocklisted faces, allowlisted faces, faces from approved sessions, and imported user-profile faces, ranking blocklisted entries first. * **`save_api_request`** (default `true`) — persists the call as an API-type session and enrolls the searched face into your face search index. Faces enrolled by Face Search calls are excluded from future Face Search results. Set to `false` to query without storing or enrolling. * **`rotate_image`** (default `false`) — tries 90-degree rotations and keeps the orientation with the best face detection; useful when EXIF orientation is missing. ## Examples ### Blocklist hit (forces `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." } ] } ``` ### Duplicate signal (status stays `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." } ] } ``` ## Related * [Face Search report](/core-technology/face-search/report-face-search) — full response shape * [Face Search API reference](/standalone-apis/face-search) — request parameters * [Face Match warnings](/core-technology/id-verification/warnings-id-verification) — 1:1 selfie-to-document warnings (separate from Face Search) * [Data models — Face Search](/reference/data-models#face-search) — canonical schema ### Warning types