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

# Cerca facial 1:N: advertències i codis d'error

> Didit explica les advertències de Cerca facial 1:N: cares duplicades, coincidències amb llistes de bloqueig o detecció de múltiples cares.

## Visió general

La Cerca facial emet un conjunt reduït d'advertències perquè el teu equip pugui saber **per què** una cerca ha retornat `Approved` o `Declined`. Les advertències es retornen a l'array `face_search.warnings[]` de la resposta de `POST /v3/face-search/` (consulta l'[informe de Cerca facial](https://docs.didit.me/ca/core-technology/face-search/report-face-search.md)).

Les advertències d'aquesta secció utilitzen una **estructura reduïda** en comparació amb les advertències dels fluxos de treball: no hi ha cap `node_id`. El contracte de resposta documentat declara cinc camps — `risk`, `additional_data`, `log_type`, `short_description`, `long_description` —, i el payload en temps d'execució inclou addicionalment `feature`, que sempre és `"LIVENESS"` en aquest endpoint.

## Advertències generades

| Risc | Causa | Gravetat (`log_type`) | Afecta l'estat | Correcció recomanada |
| - | - | - | - | - |
| `FACE_IN_BLOCKLIST` | La imatge de cerca ha coincidit amb una cara de la llista de bloqueig de cares de la teva aplicació per sobre de la banda de similitud d'alta confiança. | `error` | Força `Declined`. | Rebutja l'usuari. Investiga la sessió vinculada mitjançant `additional_data.blocklisted_session_id`. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Una cara de la llista de bloqueig ha coincidit dins de la banda inferior de similitud "possible", per sota de la banda d'alta confiança. | `error` | Força `Declined` a l'API independent de Cerca facial (més estricta que la comprovació de prova de vida del flux de treball, que envia aquest risc a revisió). | Revisió manual. Confirma la coincidència amb l'evidència original de la llista de bloqueig abans d'actuar. |
| `MULTIPLE_FACES_DETECTED` | S'ha trobat més d'una cara a la imatge de cerca enviada. La cerca s'executa igualment, utilitzant la cara detectada més gran. | `warning` | Cap — mai rebutja per si sola. | Torna a capturar amb un sol subjecte a l'enquadrament si la cara més gran no és la desitjada. |
| `DUPLICATED_FACE` | La cara ha coincidit, per sobre de la banda d'alta confiança, amb una cara d'una sessió **aprovada** o una cara de perfil d'usuari importada. L'endpoint independent no exclou sessions amb el mateix `vendor_data`, de manera que un usuari recurrent coincideix amb les seves pròpies sessions anteriors. | `information` | Cap — els duplicats es mostren com a senyal, no com a rebutjos. | Investiga la sessió vinculada mitjançant `additional_data.duplicated_session_id`. Decideix si vols bloquejar o fusionar comptes pel teu compte. |
| `POSSIBLE_DUPLICATED_FACE` | El mateix que `DUPLICATED_FACE`, però la similitud se situa a la banda inferior "possible" en lloc de la banda d'alta confiança. | `information` | Cap. | Revisió manual abans de tractar els dos registres com la mateixa persona. |

Emissor: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); derivació de l'estat: `get_face_search_status` (`apis/views/face_search.py:242-248`), que rebutja **únicament** pels dos riscos de llista de bloqueig.

Regles d'emissió que val la pena conèixer:

* **La llista de bloqueig té prioritat sobre els duplicats.** Una coincidència confirmada a la llista de bloqueig suprimeix `DUPLICATED_FACE`, i una possible coincidència a la llista de bloqueig suprimeix `POSSIBLE_DUPLICATED_FACE`; mai s'obtenen tots dos membres d'un parell per a la mateixa banda de confiança.
* **`additional_data` fa referència només a la primera cara coincident**, fins i tot quan `matches[]` en conté diverses. Les advertències de llista de bloqueig inclouen `{blocklisted_session_id, blocklisted_session_number, api_service}`; les advertències de duplicats inclouen `{duplicated_session_id, duplicated_session_number, api_service}`; `MULTIPLE_FACES_DETECTED` conté `null`. El valor de `api_service` està en majúscules (per exemple, `PASSIVE_LIVENESS`) o és `null` per a sessions de flux de treball.
* **Les cares a la llista de permisos suprimeixen les advertències de duplicats**: una coincidència d'alta confiança a la llista de permisos elimina `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (mai elimina les advertències de llista de bloqueig).

### Cadenes exactes de les advertències

| Risc | `short_description` | `long_description` |
| - | - | - |
| `FACE_IN_BLOCKLIST` | Cara a la llista de bloqueig | El sistema ha identificat una cara a la llista de bloqueig, la qual cosa significa que no es permet verificar la cara. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Possible cara a la llista de bloqueig | El sistema ha identificat una possible cara a la llista de bloqueig, la qual cosa significa que no es permet verificar la cara. |
| `DUPLICATED_FACE` | Cara duplicada d'una altra sessió aprovada | El sistema ha identificat una cara duplicada d'una altra sessió aprovada, la qual cosa requereix una investigació addicional. |
| `POSSIBLE_DUPLICATED_FACE` | Possible cara duplicada d'una altra sessió aprovada | El sistema ha identificat una possible cara duplicada d'una altra sessió aprovada, la qual cosa requereix una investigació addicional. |
| `MULTIPLE_FACES_DETECTED` | S'han detectat múltiples cares | S'han detectat múltiples cares a la imatge de prova de vida. El sistema utilitza la cara més gran per a la verificació de la prova de vida i la comparació facial, però la presència de múltiples cares pot requerir una revisió addicional. |

### Control de la imatge de cerca

Quan no es detecta cap cara a `user_image`, l'API rebutja la sol·licitud amb HTTP `400` i `{"error": "No face detected in the image"}` **abans** que es construeixi un objecte `face_search`, de manera que mai apareix una advertència `NO_FACE_DETECTED` en una resposta satisfactòria de Cerca facial. Això es retorna com una cadena `error` de primer nivell, no a `warnings[]`.

## Opcions de configuració

Les bandes de similitud que separen les coincidències confirmades (`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`) de les possibles coincidències (`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`) estan fixades internament; l'ajust de llindars per aplicació s'aplica a la comprovació de prova de vida del flux de treball, no a aquest endpoint. Els paràmetres que controles per sol·licitud són:

* **`search_type`** (`most_similar`, per defecte | `blocklisted_or_approved`) — `most_similar` classifica cada cara registrada per similitud; `blocklisted_or_approved` restringeix els candidats a cares a la llista de bloqueig, cares a la llista de permisos, cares de sessions aprovades i cares importades de perfils d'usuari, classificant en primer lloc les entrades de la llista de bloqueig.
* **`save_api_request`** (per defecte `true`) — desa la crida com una sessió de tipus API i incorpora la cara cercada al teu índex de cerca facial. Les cares incorporades mitjançant crides de Cerca facial s'exclouen dels futurs resultats de Cerca facial. Estableix-ho a `false` per consultar sense desar ni incorporar.
* **`rotate_image`** (per defecte `false`) — prova rotacions de 90 graus i manté l'orientació amb la millor detecció facial; és útil quan falta l'orientació EXIF.

## Exemples

### Coincidència amb la llista de bloqueig (força `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."
    }
  ]
}
```

### Senyal de duplicat (l'estat es manté `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."
    }
  ]
}
```

## Relacionat

* [Informe de Cerca facial](https://docs.didit.me/ca/core-technology/face-search/report-face-search.md) — estructura completa de la resposta
* [Referència de l'API de Cerca facial](https://docs.didit.me/ca/standalone-apis/face-search.md) — paràmetres de la sol·licitud
* [Advertències de Coincidència facial](https://docs.didit.me/ca/core-technology/id-verification/warnings-id-verification.md) — advertències 1:1 de selfie a document (separades de Cerca facial)
* [Models de dades — Cerca facial](https://docs.didit.me/ca/reference/data-models.md#cerca-facial) — esquema canònic

### Tipus d'advertències


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