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

# Avvisi e codici di errore del Confronto facciale

> Tutti gli avvisi del Confronto facciale 1:1 di Didit con causa, gravità e risoluzione: bassa somiglianza, immagine mancante e tentativi esauriti.

## Panoramica

Gli avvisi nel report di confronto facciale segnalano ogni condizione rilevata da Didit durante l'esecuzione del confronto facciale 1:1. Vengono inseriti nell'array `warnings[]` di ogni elemento di `face_matches[]` (vedi [Report di confronto facciale](https://docs.didit.me/it/core-technology/face-match/report-face-match.md)). Ciascuna voce include anche `feature: "FACEMATCH"` e il `node_id` del nodo del workflow che l'ha generata.

Ogni avviso si articola su tre livelli:

1. **Il codice `risk`** — un identificatore stabile su cui puoi basare i controlli nel tuo codice.
2. **Il `log_type`** — `information`, `warning` o `error`, derivato dalle soglie del punteggio di similarità del tuo workflow.
3. **L'impatto sulla decisione** — determinato dalle soglie di revisione e rifiuto del workflow per il punteggio di similarità.

Il modulo di confronto facciale è intenzionalmente essenziale — esistono esattamente cinque codici di rischio, elencati di seguito per intero.

## Condizioni di rifiuto automatico

Il seguente rischio impone sempre lo stato `Declined` per il report di confronto facciale (e per la sessione):

| Rischio | Trigger |
| - | - |
| `NO_REFERENCE_IMAGE` | Manca `source_image` (riferimento) oppure `target_image` (selfie), rendendo impossibile qualsiasi confronto. |

Quando scatta `NO_REFERENCE_IMAGE`, `LOW_FACE_MATCH_SIMILARITY` viene soppresso (non c'è nulla a cui assegnare un punteggio).

C'è un'eccezione.
Quando il passaggio di verifica dell'identità è stato completato tramite una [ricerca non documentale](https://docs.didit.me/it/core-technology/id-verification/non-doc-lookup.md) il cui registro non restituisce alcun ritratto e non verifica alcun volto, il confronto facciale non ha nulla con cui confrontare l'acquisizione dal vivo per progettazione.
Questo caso viene segnalato come `FACE_MATCH_NOT_COMPUTED` con un punteggio `null` e deciso da `face_match_not_computed_action` (di seguito), e non come rifiuto automatico.

## Impostazioni di verifica configurabili

Nella console Didit, il punteggio di similarità del confronto facciale è regolato da due soglie (nessun selettore Approva/Revisione/Rifiuta):

| Impostazione | Valore predefinito | Comportamento |
| - | - | - |
| `face_match_score_review_threshold` | 70 | Quando `score` ≤ questo valore, scatta `LOW_FACE_MATCH_SIMILARITY` e lo stato passa a `In Review`. |
| `face_match_score_decline_threshold` | 50 | Quando `score` ≤ questo valore, lo stesso avviso passa a `error` e lo stato si sposta su `Declined`. |

Aumenta la soglia di revisione se riscontri troppe approvazioni false; abbassa la soglia di rifiuto se riscontri troppi rifiuti falsi.

Un'impostazione separata controlla cosa accade quando un punteggio di similarità **non può essere calcolato affatto**: non è stato rilevato alcun volto in una delle immagini oppure una ricerca non documentale non ha lasciato alcun riferimento con cui effettuare il confronto:

| Impostazione | Valore predefinito | Comportamento |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | Azione applicata una volta che l'esito "impossibile calcolare" diventa definitivo. `REVIEW` invia il report a `In Review`; `DECLINE` lo imposta su `Declined`. (Non è prevista alcuna opzione di approvazione automatica — un punteggio mai calcolato non viene mai approvato silenziosamente.) |

Questa azione gestisce `FACE_MATCH_NOT_COMPUTED` (nessun volto nel ritratto del documento, o nessun riferimento dopo una ricerca non documentale) e un caso `NO_FACE_IN_SELFIE` esaurito (nessun volto nel selfie dopo i nuovi tentativi dell'utente). Quando il problema è il selfie, all'utente viene prima chiesto di effettuare una nuova acquisizione — vedi sotto — e l'azione si applica solo se il volto continua a non essere rilevato una volta esaurito il numero massimo di tentativi a disposizione.

Anche i fallimenti per bassa similarità entrano in un ciclo di tentativi di acquisizione prima che lo stato diventi definitivo: l'utente ha a disposizione fino a `face_match_max_attempts` tentativi totali (valore predefinito 3, configurabile tra 2 e 5 per nodo del workflow) per ripetere l'acquisizione. Un fallimento `NO_FACE_IN_SELFIE` utilizza lo stesso ciclo di nuovi tentativi, poiché l'acquisizione di un selfie più nitido può risolvere il problema. Un fallimento `FACE_MATCH_NOT_COMPUTED` **non** prevede nuovi tentativi — il ritratto del documento non può essere riacquisito in questo passaggio. Solo quando i tentativi a disposizione sono esauriti viene applicato lo stato dell'ultimo tentativo — e viene registrato `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`.

Sull'[API Face Match](https://docs.didit.me/it/standalone-apis/face-match.md) autonoma esiste solo una soglia di rifiuto (opzione della richiesta `face_match_score_decline_threshold`, valore predefinito 30); qualsiasi avviso attivato rifiuta la richiesta, e `NO_REFERENCE_IMAGE` scatta quando non è stato possibile confrontare alcun volto.

## Avvisi generati

| Rischio | Causa | Gravità | Influisce sullo stato? | Rimedio |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. Soppresso quando è presente anche `NO_REFERENCE_IMAGE`. | `warning` tra le soglie; `error` alla soglia di rifiuto o al di sotto di essa | `In Review` tra le soglie; `Declined` alla soglia di rifiuto o al di sotto di essa | Modifica le soglie oppure accetta tramite revisione manuale. |
| `FACE_MATCH_NOT_COMPUTED` | Non è stato possibile calcolare un punteggio di somiglianza perché non è stato rilevato alcun volto nella **foto del documento**, oppure perché il passaggio ID era una [ricerca senza documento](https://docs.didit.me/it/core-technology/id-verification/non-doc-lookup.md) che non ha lasciato alcun riferimento con cui effettuare il confronto (un registro che non restituisce foto e non verifica volti). Soppresso quando è presente anche `NO_REFERENCE_IMAGE`. | `warning` quando `face_match_not_computed_action` è `REVIEW`; `error` quando è `DECLINE` | `In Review` o `Declined`, in base a `face_match_not_computed_action` | L'immagine del documento non può essere riacquisita in questo passaggio: risolvi tramite revisione manuale, oppure riacquisisci il documento prima nel flusso. Dopo una ricerca basata solo sui dati, imposta `face_match_not_computed_action` sull'esito desiderato, oppure richiedi un documento nei paesi in cui il confronto biometrico è fondamentale. |
| `NO_FACE_IN_SELFIE` | Non è stato possibile calcolare un punteggio di somiglianza perché non è stato rilevato alcun volto nel **selfie** dell'utente. All'utente viene chiesto di ripetere il selfie prima che questo esito diventi definitivo. | `warning` quando `face_match_not_computed_action` è `REVIEW`; `error` quando è `DECLINE` | `In Review` o `Declined`, in base a `face_match_not_computed_action`, una volta esauriti i tentativi | L'utente acquisisce nuovamente un selfie più nitido, ben illuminato e frontale. |
| `NO_REFERENCE_IMAGE` | Manca l'immagine di riferimento o l'immagine di destinazione (a eccezione di un riferimento mai prodotto da una ricerca senza documento, che genera invece `FACE_MATCH_NOT_COMPUTED`). | `error` | **Rifiuto automatico** | Assicurati che vengano acquisiti sia la foto del documento sia il selfie per il rilevamento della vitalità. Per l'API autonoma, passa due immagini di volti valide. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | L'utente ha esaurito il numero massimo di nuovi tentativi di acquisizione (`face_match_max_attempts`) a seguito di ripetuti fallimenti per bassa somiglianza. | `information` | No — registra che è stato applicato lo stato calcolato dell'ultimo tentativo (rifiuto o revisione) | Aumenta `face_match_max_attempts` sul nodo del workflow, oppure risolvi tramite revisione manuale. |

## Esempi

### In revisione — somiglianza al limite

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

### In revisione — impossibilità di calcolare il confronto facciale

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

### Rifiuto automatico — riferimento mancante

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

### Tentativi esauriti — applicato lo stato dell'ultimo tentativo

```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 del confronto facciale](https://docs.didit.me/it/standalone-apis/face-match.md) autonoma restituisce la stessa struttura di avvisi senza `node_id` (il confronto non è vincolato a un nodo del workflow).

## Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. Le tre gravità sono:

## Correlati

* [Report del confronto facciale](https://docs.didit.me/it/core-technology/face-match/report-face-match.md) — schema completo del report e stati.
* [Avvisi sul rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/warnings-liveness.md) — avvisi a monte sull'acquisizione del selfie.
* [Webhook](https://docs.didit.me/it/integration/webhooks.md) — `session.status.updated` include gli avvisi non appena il passaggio termina.
* [Modelli di dati — Confronto facciale](https://docs.didit.me/it/reference/data-models.md#confronto-facciale) — schema canonico.
* [Modelli di dati — Oggetto avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso) — la struttura di ciascuna voce in `warnings[]`.


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