> ## 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. # Advertencias y códigos de error de búsqueda facial 1:N > Códigos de advertencia de búsqueda facial 1:N de Didit: coincidencias en lista de bloqueo, rostros duplicados, varios rostros e imágenes sin rostro. ## Descripción general Face Search emite un pequeño conjunto de advertencias para que tu equipo pueda saber **por qué** una búsqueda devolvió `Approved` o `Declined`. Las advertencias se devuelven en el array `face_search.warnings[]` de la respuesta de `POST /v3/face-search/` (consulta el [informe de Face Search](https://docs.didit.me/es/core-technology/face-search/report-face-search.md)). Aquí las advertencias usan una **estructura reducida** en comparación con las advertencias del flujo de verificación (workflow): no hay `node_id`. El contrato de respuesta documentado declara cinco campos (`risk`, `additional_data`, `log_type`, `short_description`, `long_description`), y el payload en tiempo de ejecución incluye además `feature`, que siempre es `"LIVENESS"` en este endpoint. ## Advertencias generadas | Riesgo | Causa | Gravedad (`log_type`) | Afecta al estado | Solución recomendada | | - | - | - | - | - | | `FACE_IN_BLOCKLIST` | La imagen de búsqueda coincidió con un rostro de la lista de bloqueo facial de tu aplicación por encima de la banda de similitud de alta confianza. | `error` | Fuerza `Declined`. | Rechaza al usuario. Investiga la sesión vinculada mediante `additional_data.blocklisted_session_id`. | | `POSSIBLE_FACE_IN_BLOCKLIST` | Un rostro de la lista de bloqueo coincidió dentro de la banda de similitud "posible", más baja, por debajo de la banda de alta confianza. | `error` | Fuerza `Declined` en la API independiente de Búsqueda facial (más estricta que la comprobación de prueba de vida del flujo, que envía este riesgo a revisión). | Revisión manual. Confirma la coincidencia con la evidencia original de la lista de bloqueo antes de actuar. | | `MULTIPLE_FACES_DETECTED` | Se encontró más de un rostro en la imagen de búsqueda enviada. La búsqueda se ejecuta igualmente, usando el rostro detectado más grande. | `warning` | Ninguno: nunca rechaza por sí sola. | Vuelve a capturar la imagen con una sola persona en el encuadre si el rostro más grande no es el esperado. | | `DUPLICATED_FACE` | El rostro coincidió, por encima de la banda de alta confianza, con un rostro de una sesión con estado **aprobado** o con un rostro de perfil de usuario importado. El endpoint independiente no excluye las sesiones con el mismo `vendor_data`, por lo que un usuario recurrente coincide con sus propias sesiones anteriores. | `information` | Ninguno: los duplicados se muestran como señal, no como rechazos. | Investiga la sesión vinculada mediante `additional_data.duplicated_session_id`. Decide en tu sistema si bloquear o fusionar las cuentas. | | `POSSIBLE_DUPLICATED_FACE` | Igual que `DUPLICATED_FACE`, pero la similitud se sitúa en la banda "posible", más baja, en lugar de en la banda de alta confianza. | `information` | Ninguno. | Revisión manual antes de tratar los dos registros como la misma persona. | Generador: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); derivación del estado: `get_face_search_status` (`apis/views/face_search.py:242-248`), que rechaza **solo** en los dos riesgos de lista de bloqueo. Reglas de emisión que conviene conocer: * **La lista de bloqueo tiene prioridad sobre los duplicados.** Una coincidencia confirmada en la lista de bloqueo suprime `DUPLICATED_FACE`, y una posible coincidencia en la lista de bloqueo suprime `POSSIBLE_DUPLICATED_FACE`: nunca recibes ambos miembros de un par para la misma banda de confianza. * **`additional_data` hace referencia solo al primer rostro coincidente**, aunque `matches[]` contenga varios. Las advertencias de lista de bloqueo incluyen `{blocklisted_session_id, blocklisted_session_number, api_service}`; las advertencias de duplicados incluyen `{duplicated_session_id, duplicated_session_number, api_service}`; `MULTIPLE_FACES_DETECTED` incluye `null`. El valor de `api_service` está en mayúsculas (p. ej., `PASSIVE_LIVENESS`) o es `null` en las sesiones del flujo de trabajo. * **Los rostros de la lista de permitidos suprimen las advertencias de duplicados**: una coincidencia de alta confianza con la lista de permitidos elimina `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (nunca elimina las advertencias de lista de bloqueo). ### Textos exactos de las advertencias | Riesgo | `short_description` | `long_description` | | - | - | - | | `FACE_IN_BLOCKLIST` | Rostro en la lista de bloqueo | El sistema identificó un rostro en la lista de bloqueo, lo que significa que no se permite verificar ese rostro. | | `POSSIBLE_FACE_IN_BLOCKLIST` | Posible rostro en la lista de bloqueo | El sistema identificó un posible rostro en la lista de bloqueo, lo que significa que no se permite verificar ese rostro. | | `DUPLICATED_FACE` | Rostro duplicado de otra sesión aprobada | El sistema identificó un rostro duplicado de otra sesión aprobada, lo que requiere una investigación adicional. | | `POSSIBLE_DUPLICATED_FACE` | Posible rostro duplicado de otra sesión aprobada | El sistema identificó un posible rostro duplicado de otra sesión aprobada, lo que requiere una investigación adicional. | | `MULTIPLE_FACES_DETECTED` | Se detectaron varios rostros | Se detectaron varios rostros en la imagen de prueba de vida. El sistema usa el rostro más grande para la verificación de prueba de vida y la comparación facial, pero la presencia de varios rostros puede requerir una revisión adicional. | ### Validación previa de la imagen de búsqueda Cuando no se detecta ningún rostro en `user_image`, la API rechaza la solicitud con HTTP `400` y `{"error": "No face detected in the image"}` **antes** de construir un objeto `face_search`, por lo que una advertencia `NO_FACE_DETECTED` nunca aparece en una respuesta exitosa de Búsqueda facial. Esto se devuelve como una cadena `error` de nivel superior, no en `warnings[]`. ## Configuración disponible Las bandas de similitud que separan las coincidencias confirmadas (`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`) de las posibles (`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`) son fijas internamente: el ajuste de umbrales por aplicación se aplica a la comprobación de prueba de vida del flujo, no a este endpoint. Los parámetros que controlas en cada solicitud son: * **`search_type`** (`most_similar`, valor predeterminado | `blocklisted_or_approved`): `most_similar` ordena todos los rostros registrados por similitud; `blocklisted_or_approved` limita los candidatos a los rostros de la lista de bloqueo, los rostros de la lista de permitidos, los rostros de sesiones aprobadas y los rostros de perfiles de usuario importados, y sitúa primero las entradas de la lista de bloqueo. * **`save_api_request`** (valor predeterminado `true`): guarda la llamada como una sesión de tipo API y registra el rostro buscado en tu índice de búsqueda facial. Los rostros registrados mediante llamadas de Face Search se excluyen de los resultados futuros de Face Search. Establécelo en `false` para consultar sin almacenar ni registrar. * **`rotate_image`** (valor predeterminado `false`): prueba rotaciones de 90 grados y conserva la orientación con la mejor detección facial; resulta útil cuando falta la orientación EXIF. ## Ejemplos ### Coincidencia en la lista de bloqueo (fuerza `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." } ] } ``` ### Señal de duplicado (el estado se mantiene en `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." } ] } ``` ## Relacionado * [Informe de Búsqueda facial](https://docs.didit.me/es/core-technology/face-search/report-face-search.md): estructura completa de la respuesta * [Referencia de la API de Búsqueda facial](https://docs.didit.me/es/standalone-apis/face-search.md): parámetros de la solicitud * [Advertencias de Coincidencia facial](https://docs.didit.me/es/core-technology/id-verification/warnings-id-verification.md): advertencias de la comparación 1:1 entre selfie y documento (independientes de Búsqueda facial) * [Modelos de datos: Búsqueda facial](https://docs.didit.me/es/reference/data-models.md#búsqueda-facial): esquema canónico ### Tipos de advertencia This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.