> ## 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 Face Match

> Advertencias del face match 1:1 de Didit (baja similitud, sin imagen de referencia, reintentos agotados): causa, gravedad y solución.

## 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](https://docs.didit.me/es/core-technology/face-match/report-face-match.md)). 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:

1. **El código `risk`**: un identificador estable que puedes usar para identificarla en tu código.
2. **El `log_type`**: `information`, `warning` o `error`, que se deriva de los umbrales de puntuación de similitud de tu flujo.
3. **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](https://docs.didit.me/es/core-technology/id-verification/non-doc-lookup.md) 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](https://docs.didit.me/es/standalone-apis/face-match.md) 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](https://docs.didit.me/es/core-technology/id-verification/non-doc-lookup.md) 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

```json theme={null}
"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

```json theme={null}
"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

```json theme={null}
"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

```json theme={null}
"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"
  }
]
```

> [!NOTE]
>
> La [API de coincidencia facial](https://docs.didit.me/es/standalone-apis/face-match.md) 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](https://docs.didit.me/es/core-technology/face-match/report-face-match.md): esquema completo del informe y estados.
* [Advertencias de prueba de vida](https://docs.didit.me/es/core-technology/liveness/warnings-liveness.md): advertencias de la prueba de vida sobre la captura de la selfie.
* [Webhooks](https://docs.didit.me/es/integration/webhooks.md): `session.status.updated` incluye las advertencias en cuanto termina el paso.
* [Modelos de datos: coincidencia facial](https://docs.didit.me/es/reference/data-models.md#coincidencia-facial): esquema canónico.
* [Modelos de datos: objeto de advertencia](https://docs.didit.me/es/reference/data-models.md#objeto-de-advertencia): la estructura de cada entrada de `warnings[]`.


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