Advertencias y códigos de error de búsqueda facial 1:N

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). 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`)

{
  "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`)

{
  "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: estructura completa de la respuesta
Referencia de la API de Búsqueda facial: parámetros de la solicitud
Advertencias de Coincidencia facial: advertencias de la comparación 1:1 entre selfie y documento (independientes de Búsqueda facial)
Modelos de datos: Búsqueda facial: esquema canónico

Autenticación

Verificación

Monitorización

Plataforma

Advertencias y códigos de error de búsqueda facial 1:N

Descripción general

Advertencias generadas

Textos exactos de las advertencias

Validación previa de la imagen de búsqueda

Configuración disponible

Ejemplos

Coincidencia en la lista de bloqueo (fuerza `Declined`)

Señal de duplicado (el estado se mantiene en `Approved`)

Relacionado

Tipos de advertencia

​Descripción general

​Advertencias generadas

​Textos exactos de las advertencias

​Validación previa de la imagen de búsqueda

​Configuración disponible

​Ejemplos

​Coincidencia en la lista de bloqueo (fuerza Declined)

​Señal de duplicado (el estado se mantiene en Approved)

​Relacionado

​Tipos de advertencia

Descripción general

Advertencias generadas

Textos exactos de las advertencias

Validación previa de la imagen de búsqueda

Configuración disponible

Ejemplos

Coincidencia en la lista de bloqueo (fuerza `Declined`)

Señal de duplicado (el estado se mantiene en `Approved`)

Relacionado

Tipos de advertencia