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

# Coincidència facial: advertències i codis d'error

> Totes les advertències del mòdul 1:1 de Coincidència facial de Didit: causes, gravetat i resolució per a similitud baixa o reintents esgotats.

## Visió general

Les advertències a l'informe de coincidència facial assenyalen cada condició que Didit ha detectat en executar la comparació facial 1:1. Es recullen a l'array `warnings[]` de cada element de `face_matches[]` (consulta [Informe de coincidència facial](https://docs.didit.me/ca/core-technology/face-match/report-face-match.md)). Cada entrada també inclou `feature: "FACEMATCH"` i el `node_id` del node del flux de treball que l'ha generada.

Cada advertència té tres capes:

1. **El codi de `risk`** — un identificador estable amb què pots fer comparacions al teu codi.
2. **El `log_type`** — `information`, `warning` o `error`, derivat dels llindars de puntuació de similitud del teu flux de treball.
3. **L'impacte en la decisió** — determinat pels llindars de revisió i rebuig del flux de treball per a la puntuació de similitud.

El mòdul de coincidència facial és intencionadament reduït: hi ha exactament cinc codis de risc, que es detallen a continuació.

## Condicions de rebuig automàtic

El risc següent sempre força l'estat de l'informe de coincidència facial (i de la sessió) a `Declined`:

| Risc | Activador |
| - | - |
| `NO_REFERENCE_IMAGE` | Falta una de les dues imatges, `source_image` (referència) o `target_image` (selfie), de manera que no ha estat possible fer cap comparació. |

Quan s'activa `NO_REFERENCE_IMAGE`, se suprimeix `LOW_FACE_MATCH_SIMILARITY` (no hi ha res per puntuar).

Hi ha una excepció.
Quan el pas d'identificació s'ha completat mitjançant una [consulta sense document](https://docs.didit.me/ca/core-technology/id-verification/non-doc-lookup.md) en què el registre no retorna cap retrat ni comprova cap cara, Coincidència facial no té res amb què comparar la captura en directe per disseny.
Això s'informa com a `FACE_MATCH_NOT_COMPUTED` amb una puntuació `null` i es decideix mitjançant `face_match_not_computed_action` (més avall), no pas com un rebuig automàtic.

## Configuració de verificació

A la consola de Didit, la puntuació de similitud de coincidència facial es regeix per dos llindars (sense commutador Approve/Review/Decline):

| Configuració | Per defecte | Comportament |
| - | - | - |
| `face_match_score_review_threshold` | 70 | Quan `score` és inferior o igual a aquest valor, s'activa `LOW_FACE_MATCH_SIMILARITY` i l'estat passa a `In Review`. |
| `face_match_score_decline_threshold` | 50 | Quan `score` és inferior o igual a aquest valor, la mateixa advertència s'eleva al nivell `error` i l'estat passa a `Declined`. |

Ajusta el llindar de revisió a un valor més alt si detectes massa aprovacions falses; ajusta el llindar de rebuig a un valor més baix si detectes massa rebuigs falsos.

Una configuració independent controla què passa quan una puntuació de similitud **no es pot calcular de cap manera**: no s'ha detectat cap cara en una de les imatges, o bé una consulta sense document no ha deixat cap referència contra la qual comparar:

| Configuració | Per defecte | Comportament |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | Acció que s'aplica un cop el resultat de «no s'ha pogut calcular» esdevé definitiu. `REVIEW` envia l'informe a `In Review`; `DECLINE` l'estableix a `Declined`. (No hi ha cap opció d'aprovació automàtica: una puntuació que no s'ha calculat mai no s'aprova silenciosament). |

Aquesta acció regeix `FACE_MATCH_NOT_COMPUTED` (sense cara al retrat del document, o sense cap referència després d'una consulta sense document) i un `NO_FACE_IN_SELFIE` esgotat (sense cara a la selfie després dels reintents de l'usuari). Quan el problema és la selfie, primer es demana a l'usuari que torni a fer la captura (consulta més avall) i l'acció només s'aplica si encara no es pot detectar cap cara un cop s'ha esgotat el límit d'intents.

Els errors per baixa similitud també entren en un bucle de reintent de captura abans que l'estat es consolidi: l'usuari disposa de fins a `face_match_max_attempts` intents en total (3 per defecte, configurable entre 2 i 5 per node del flux de treball) per tornar a fer la captura. Un error per `NO_FACE_IN_SELFIE` utilitza el mateix bucle de reintents, ja que tornar a fer una captura més clara de la selfie pot solucionar-ho. Un error per `FACE_MATCH_NOT_COMPUTED` **no** es reintenta: el retrat del document no es pot tornar a capturar en aquest pas. Només quan s'esgota el límit d'intents s'aplica l'estat del darrer intent, i es registra `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` per deixar-ne constància.

A l'[API de coincidència facial](https://docs.didit.me/ca/standalone-apis/face-match.md) autònoma només existeix un llindar de rebuig (opció de sol·licitud `face_match_score_decline_threshold`, per defecte 30); qualsevol advertència que s'activi rebutja la sol·licitud, i `NO_REFERENCE_IMAGE` s'activa quan no s'ha pogut comparar cap cara en absolut.

## Advertències generades

| Risc | Causa | Gravetat | Afecta l'estat? | Solució |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. Se suprimeix quan `NO_REFERENCE_IMAGE` també és present. | `warning` entre els llindars; `error` al llindar de rebuig o per sota | `In Review` entre els llindars; `Declined` al llindar de rebuig o per sota | Ajusta els llindars o accepta mitjançant revisió manual. |
| `FACE_MATCH_NOT_COMPUTED` | No s'ha pogut calcular una puntuació de similitud perquè no s'ha detectat cap cara al **retrat del document**, o perquè el pas d'identificació era una [consulta sense document](https://docs.didit.me/ca/core-technology/id-verification/non-doc-lookup.md) que no ha deixat cap referència amb la qual comparar (un registre que no retorna cap retrat i no comprova cap cara). Se suprimeix quan `NO_REFERENCE_IMAGE` també és present. | `warning` quan `face_match_not_computed_action` és `REVIEW`; `error` quan és `DECLINE` | `In Review` o `Declined`, segons `face_match_not_computed_action` | La imatge del document no es pot tornar a capturar en aquest pas: resol mitjançant revisió manual o torna a capturar el document prèviament en el flux. Després d'una consulta de només dades, defineix `face_match_not_computed_action` amb el resultat que vulguis, o exigeix un document en països on la coincidència biomètrica sigui rellevant. |
| `NO_FACE_IN_SELFIE` | No s'ha pogut calcular una puntuació de similitud perquè no s'ha detectat cap cara a la **selfie** de l'usuari. Es demana a l'usuari que torni a fer-se la selfie abans que es confirmi aquesta advertència. | `warning` quan `face_match_not_computed_action` és `REVIEW`; `error` quan és `DECLINE` | `In Review` o `Declined`, segons `face_match_not_computed_action`, un cop esgotats els reintents | L'usuari torna a capturar una selfie més clara, ben il·luminada i frontal. |
| `NO_REFERENCE_IMAGE` | Falta la imatge de referència o la imatge d'objectiu (tret d'una referència que una consulta sense document mai no hagi generat, que és `FACE_MATCH_NOT_COMPUTED`). | `error` | **Rebuig automàtic** | Assegura't que es capturin tant el retrat del document com la selfie de prova de vida. Per a l'API independent, passa dues imatges facials vàlides. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | L'usuari ha esgotat el límit de reintents de captura (`face_match_max_attempts`) després de fallades repetides de baixa similitud. | `information` | No: registra que s'ha aplicat l'estat calculat de l'últim intent (rebuig o revisió) | Augmenta `face_match_max_attempts` al node del flux de treball o resol mitjançant revisió manual. |

## Exemples

### En revisió: similitud limítrofa

```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ó: no s'ha pogut calcular la coincidència 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"
  }
]
```

### Rebuig automàtic: falta la referència

```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"
  }
]
```

### Reintents esgotats: s'ha aplicat l'estat de l'últim intent

```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]
>
> L'[API de coincidència facial](https://docs.didit.me/ca/standalone-apis/face-match.md) independent retorna la mateixa estructura d'advertència menys `node_id` (la comparació no està vinculada a un node del flux de treball).

## Tipus d'advertència

A cada risc se li assigna una gravetat basada en la configuració de la teva aplicació. Les tres gravetats són:

## Relacionat

* [Informe de coincidència facial](https://docs.didit.me/ca/core-technology/face-match/report-face-match.md): esquema complet de l'informe i estats.
* [Advertències de prova de vida](https://docs.didit.me/ca/core-technology/liveness/warnings-liveness.md): advertències prèvies durant la captura de la selfie.
* [Webhooks](https://docs.didit.me/ca/integration/webhooks.md): `session.status.updated` transmet les advertències tan bon punt finalitza el pas.
* [Models de dades: Coincidència facial](https://docs.didit.me/ca/reference/data-models.md#coincidència-facial): esquema canònic.
* [Models de dades: Objecte d'advertència](https://docs.didit.me/ca/reference/data-models.md#objecte-d’advertència): estructura de cada entrada de `warnings[]`.


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