Advertencias y códigos de error de Face Match

Descripción general

Las advertencias del informe de coincidencia facial señalan cada condición que Didit observó al ejecutar la comparación facial 1:1. Se incluyen en el array warnings[] de cada elemento de face_matches[] (consulta Informe de coincidencia facial). Cada entrada incluye además feature: "FACEMATCH" y el node_id del nodo del flujo de verificación (workflow) que la generó. Cada advertencia tiene tres capas:

El código risk: un identificador estable que puedes usar para identificarla en tu código.
El log_type: information, warning o error, que se deriva de los umbrales de puntuación de similitud de tu flujo.
El impacto en la decisión: lo determinan los umbrales de revisión y de rechazo del flujo para la puntuación de similitud.

El módulo de coincidencia facial es deliberadamente reducido: hay exactamente cinco códigos de riesgo, que se enumeran todos a continuación.

Condiciones de rechazo automático

El siguiente riesgo siempre fuerza el informe de coincidencia facial (y la sesión) a Declined:

Riesgo	Disparador
`NO_REFERENCE_IMAGE`	Falta `source_image` (referencia) o `target_image` (selfie), por lo que no fue posible realizar la comparación.

Cuando se activa NO_REFERENCE_IMAGE, se suprime LOW_FACE_MATCH_SIMILARITY (no hay nada que puntuar). Hay una excepción. Cuando el paso de identificación se completó mediante una consulta sin documento cuyo registro no devuelve ningún retrato ni verifica ningún rostro, la coincidencia facial no tiene, por diseño, nada con lo que comparar la captura en vivo. Esto se informa como FACE_MATCH_NOT_COMPUTED con una puntuación de null y la decisión se toma según face_match_not_computed_action (ver más abajo), no como un rechazo automático.

Configuración de verificación ajustable

En la consola de Didit, la puntuación de similitud de la coincidencia facial se rige por dos umbrales (no hay selector de Aprobar/Revisar/Rechazar):

Configuración	Valor predeterminado	Comportamiento
`face_match_score_review_threshold`	70	Cuando `score` ≤ este valor, se activa `LOW_FACE_MATCH_SIMILARITY` y el estado pasa a `In Review`.
`face_match_score_decline_threshold`	50	Cuando `score` ≤ este valor, la misma advertencia pasa a ser un `error` y el estado pasa a `Declined`.

Sube el umbral de revisión si observas demasiadas aprobaciones incorrectas; baja el umbral de rechazo si observas demasiados rechazos incorrectos. Una configuración independiente controla qué ocurre cuando una puntuación de similitud no se puede calcular en absoluto: no se detectó ningún rostro en una de las imágenes, o una consulta sin documento no dejó ninguna referencia con la que comparar:

Configuración	Valor predeterminado	Comportamiento
`face_match_not_computed_action`	`REVIEW`	Acción que se aplica cuando el resultado “no se pudo calcular” es definitivo. `REVIEW` envía el informe a `In Review`; `DECLINE` lo establece en `Declined`. (No existe opción de aprobación automática: una puntuación que nunca se calculó nunca se da por buena sin más.)

Esta acción rige FACE_MATCH_NOT_COMPUTED (no hay rostro en el retrato del documento, o no hay ninguna referencia tras una consulta sin documento) y NO_FACE_IN_SELFIE después de agotar los reintentos (no hay rostro en la selfie tras los reintentos del usuario). Cuando el problema está en la selfie, primero se pide al usuario que vuelva a capturarla (ver más abajo), y la acción solo se aplica si sigue sin poder detectarse un rostro una vez agotados los intentos disponibles. Los fallos por baja similitud también entran en un ciclo de reintento de captura antes de que el estado quede fijado: el usuario dispone de hasta face_match_max_attempts intentos en total (3 de forma predeterminada, configurable entre 2 y 5 por nodo del flujo) para volver a capturar. Un fallo NO_FACE_IN_SELFIE usa el mismo ciclo de reintento, ya que capturar una selfie más nítida puede resolverlo. Un fallo FACE_MATCH_NOT_COMPUTED no se reintenta: el retrato del documento no se puede volver a capturar en este paso. Solo cuando se agotan los intentos se aplica el estado del último intento, y se registra FACE_MATCH_MAX_ATTEMPTS_EXCEEDED para dejar constancia de ello. En la API de coincidencia facial independiente solo existe un umbral de rechazo (opción de solicitud face_match_score_decline_threshold, 30 de forma predeterminada); cualquier advertencia activada rechaza la solicitud, y NO_REFERENCE_IMAGE se activa cuando no se pudo comparar ningún rostro.

Advertencias generadas

Riesgo	Causa	Gravedad	¿Afecta al estado?	Solución
`LOW_FACE_MATCH_SIMILARITY`	`score` ≤ `face_match_score_review_threshold`. Se omite cuando también está presente `NO_REFERENCE_IMAGE`.	`warning` entre los umbrales; `error` en el umbral de rechazo o por debajo de él	`In Review` entre los umbrales; `Declined` en el umbral de rechazo o por debajo de él	Ajusta los umbrales o acepta mediante revisión manual.
`FACE_MATCH_NOT_COMPUTED`	No se pudo calcular una puntuación de similitud porque no se detectó ningún rostro en el retrato del documento, o porque el paso de identificación fue una consulta sin documento que no dejó ninguna referencia con la que comparar (un registro que no devuelve ningún retrato ni verifica ningún rostro). Se omite cuando también está presente `NO_REFERENCE_IMAGE`.	`warning` cuando `face_match_not_computed_action` es `REVIEW`; `error` cuando es `DECLINE`	`In Review` o `Declined`, según `face_match_not_computed_action`, una vez agotados los reintentos	La imagen del documento no se puede volver a capturar en este paso: resuélvelo mediante revisión manual o vuelve a capturar el documento antes en el flujo. Tras una consulta solo de datos, configura `face_match_not_computed_action` con el resultado que quieras, o exige un documento en los países donde importe una coincidencia biométrica.
`NO_FACE_IN_SELFIE`	No se pudo calcular una puntuación de similitud porque no se detectó ningún rostro en la selfie del usuario. Se le pide al usuario que repita la selfie antes de que esto se dé por definitivo.	`warning` cuando `face_match_not_computed_action` es `REVIEW`; `error` cuando es `DECLINE`	`In Review` o `Declined`, según `face_match_not_computed_action`, una vez agotados los reintentos	El usuario vuelve a capturar una selfie más nítida, bien iluminada y de frente.
`NO_REFERENCE_IMAGE`	Falta la imagen de referencia o la imagen objetivo (salvo una referencia que una consulta sin documento nunca generó, que corresponde a `FACE_MATCH_NOT_COMPUTED`).	`error`	Rechazo automático	Asegúrate de que se capturen tanto el retrato del documento como la selfie de prueba de vida. Para la API independiente, envía dos imágenes faciales válidas.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	El usuario agotó el número de reintentos de captura (`face_match_max_attempts`) tras fallos repetidos por baja similitud.	`information`	No: registra que se aplicó el estado calculado en el último intento (rechazo o revisión)	Aumenta `face_match_max_attempts` en el nodo del flujo o resuélvelo mediante revisión manual.

Ejemplos

En revisión: similitud en el límite

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  }
]

En revisión: no se pudo calcular la coincidencia facial

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]

Rechazo automático: falta la referencia

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]

Reintentos agotados: se aplica el estado del último intento

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]

La API de coincidencia facial independiente devuelve la misma estructura de advertencia, sin node_id (la comparación no está vinculada a un nodo del flujo).

Tipos de advertencia

A cada riesgo se le asigna una gravedad según la configuración de tu aplicación. Las tres gravedades son:

Relacionado

Informe de coincidencia facial: esquema completo del informe y estados.
Advertencias de prueba de vida: advertencias de la prueba de vida sobre la captura de la selfie.
Webhooks: session.status.updated incluye las advertencias en cuanto termina el paso.
Modelos de datos: coincidencia facial: esquema canónico.
Modelos de datos: objeto de advertencia: la estructura de cada entrada de warnings[].

Autenticación

Verificación

Monitorización

Plataforma

Advertencias y códigos de error de Face Match

Descripción general

Condiciones de rechazo automático

Configuración de verificación ajustable

Advertencias generadas

Ejemplos

En revisión: similitud en el límite

En revisión: no se pudo calcular la coincidencia facial

Rechazo automático: falta la referencia

Reintentos agotados: se aplica el estado del último intento

Tipos de advertencia

Relacionado

​Descripción general

​Condiciones de rechazo automático

​Configuración de verificación ajustable

​Advertencias generadas

​Ejemplos

​En revisión: similitud en el límite

​En revisión: no se pudo calcular la coincidencia facial

​Rechazo automático: falta la referencia

​Reintentos agotados: se aplica el estado del último intento

​Tipos de advertencia

​Relacionado

Descripción general

Condiciones de rechazo automático

Configuración de verificación ajustable

Advertencias generadas

Ejemplos

En revisión: similitud en el límite

En revisión: no se pudo calcular la coincidencia facial

Rechazo automático: falta la referencia

Reintentos agotados: se aplica el estado del último intento

Tipos de advertencia

Relacionado