> ## 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. # Face Search 1:N: avvisi e codici di errore > Scopri gli avvisi di Face Search 1:N su Didit: corrispondenze in blocklist, volti duplicati, volti multipli ed errori di rilevamento. ## Panoramica Ricerca facciale genera un set ridotto di avvisi affinché il tuo team possa comprendere **perché** una ricerca ha restituito `Approved` o `Declined`. Gli avvisi vengono restituiti nell'array `face_search.warnings[]` della risposta `POST /v3/face-search/` (vedi [report di Ricerca facciale](https://docs.didit.me/it/core-technology/face-search/report-face-search.md)). Gli avvisi qui utilizzano un **formato ridotto** rispetto agli avvisi dei workflow: non è presente alcun `node_id`. Il contratto di risposta documentato dichiara cinque campi — `risk`, `additional_data`, `log_type`, `short_description`, `long_description` — e il payload in fase di esecuzione include inoltre `feature`, che su questo endpoint è sempre `"LIVENESS"`. ## Avvisi generati | Rischio | Causa | Gravità (`log_type`) | Influisce sullo stato | Risoluzione consigliata | | - | - | - | - | - | | `FACE_IN_BLOCKLIST` | L'immagine cercata corrisponde a un volto nella blocklist dei volti della tua applicazione al di sopra della fascia di somiglianza ad alta affidabilità. | `error` | Forza `Declined`. | Rifiuta l'utente. Esegui indagini sulla sessione collegata tramite `additional_data.blocklisted_session_id`. | | `POSSIBLE_FACE_IN_BLOCKLIST` | Un volto presente in blocklist ha trovato una corrispondenza all'interno della fascia di somiglianza inferiore "possibile", al di sotto della fascia ad alta affidabilità. | `error` | Forza `Declined` sull'API autonoma di Ricerca facciale (più rigorosa rispetto al controllo di vitalità del workflow, che invia questo rischio in revisione). | Revisione manuale. Conferma la corrispondenza con le prove originali della blocklist prima di agire. | | `MULTIPLE_FACES_DETECTED` | È stato rilevato più di un volto nell'immagine di ricerca inviata. La ricerca viene comunque eseguita, utilizzando il volto rilevato più grande. | `warning` | Nessuno — non rifiuta mai da solo. | Acquisisci nuovamente con un unico soggetto nell'inquadratura se il volto più grande non è quello previsto. | | `DUPLICATED_FACE` | Il volto corrisponde, al di sopra della fascia ad alta affidabilità, a un volto proveniente da una sessione con stato **approvato** o al volto di un profilo utente importato. L'endpoint autonomo non esclude le sessioni con lo stesso `vendor_data`, pertanto il volto di un utente che ritorna corrisponderà alle sue sessioni precedenti. | `information` | Nessuno — i duplicati vengono segnalati come segnale, non causano un rifiuto. | Esegui indagini sulla sessione collegata tramite `additional_data.duplicated_session_id`. Decidi se bloccare o unire gli account dal tuo lato. | | `POSSIBLE_DUPLICATED_FACE` | Uguale a `DUPLICATED_FACE`, ma la somiglianza rientra nella fascia inferiore "possibile" anziché nella fascia ad alta affidabilità. | `information` | Nessuno. | Revisione manuale prima di considerare i due record come la stessa persona. | Generatore: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); derivazione dello stato: `get_face_search_status` (`apis/views/face_search.py:242-248`), che rifiuta **solo** per i due rischi di blocklist. Regole di emissione utili da conoscere: * **La blocklist ha la precedenza sui duplicati.** Una corrispondenza confermata in blocklist sopprime `DUPLICATED_FACE`, e una corrispondenza possibile in blocklist sopprime `POSSIBLE_DUPLICATED_FACE` — non si ottengono mai entrambi gli elementi di una coppia per la stessa fascia di affidabilità. * **`additional_data` fa riferimento solo al primo volto corrispondente**, anche quando `matches[]` ne contiene diversi. Gli avvisi di blocklist contengono `{blocklisted_session_id, blocklisted_session_number, api_service}`; gli avvisi di duplicati contengono `{duplicated_session_id, duplicated_session_number, api_service}`; `MULTIPLE_FACES_DETECTED` contiene `null`. Il valore di `api_service` è in maiuscolo (ad es. `PASSIVE_LIVENESS`) oppure `null` per le sessioni dei workflow. * **I volti nella lista consentita sopprimono gli avvisi di duplicato** — una corrispondenza nella lista consentita ad alta affidabilità cancella `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (non cancella mai gli avvisi di blocklist). ### Stringhe esatte degli avvisi | Rischio | `short_description` | `long_description` | | - | - | - | | `FACE_IN_BLOCKLIST` | Volto in blocklist | Il sistema ha identificato un volto nella blocklist, il che significa che non è consentito verificare il volto. | | `POSSIBLE_FACE_IN_BLOCKLIST` | Possibile volto in blocklist | Il sistema ha identificato un possibile volto nella blocklist, il che significa che non è consentito verificare il volto. | | `DUPLICATED_FACE` | Volto duplicato da un'altra sessione approvata | Il sistema ha identificato un volto duplicato da un'altra sessione approvata, richiedendo ulteriori indagini. | | `POSSIBLE_DUPLICATED_FACE` | Possibile volto duplicato da un'altra sessione approvata | Il sistema ha identificato un possibile volto duplicato da un'altra sessione approvata, richiedendo ulteriori indagini. | | `MULTIPLE_FACES_DETECTED` | Rilevati più volti | Sono stati rilevati più volti nell'immagine di rilevamento della vitalità. Il sistema utilizza il volto più grande per la verifica della vitalità e il confronto facciale, ma la presenza di più volti potrebbe richiedere una revisione aggiuntiva. | ### Controllo dell'immagine di ricerca Quando non viene rilevato alcun volto in `user_image`, l'API rifiuta la richiesta con HTTP `400` e `{"error": "No face detected in the image"}` **prima** che venga creato un oggetto `face_search` — pertanto un avviso `NO_FACE_DETECTED` non compare mai in una risposta riuscita di Ricerca facciale. Questo viene restituito come stringa `error` di primo livello, non in `warnings[]`. ## Impostazioni configurabili Le fasce di somiglianza che separano le corrispondenze confermate (`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`) da quelle possibili (`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`) sono fisse internamente — la regolazione delle soglie per applicazione si applica al controllo di vitalità del workflow, non a questo endpoint. I selettori che puoi controllare per ciascuna richiesta sono: * **`search_type`** (`most_similar`, predefinito | `blocklisted_or_approved`) — `most_similar` ordina ogni volto registrato in base alla somiglianza; `blocklisted_or_approved` limita i candidati ai volti in blocklist, ai volti nella lista consentita, ai volti provenienti da sessioni approvate e ai volti di profili utente importati, ordinando per prime le voci in blocklist. * **`save_api_request`** (predefinito `true`) — rende persistente la chiamata come sessione di tipo API e registra il volto cercato nel tuo indice di ricerca facciale. I volti registrati tramite chiamate a Ricerca facciale sono esclusi dai risultati futuri di Ricerca facciale. Imposta su `false` per eseguire query senza memorizzare o registrare. * **`rotate_image`** (predefinito `false`) — tenta rotazioni di 90 gradi e mantiene l'orientamento con il miglior rilevamento del volto; utile quando l'orientamento EXIF è assente. ## Esempi ### Corrispondenza con la blocklist (forza `Declined`) ```json theme={null} { "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." } ] } ``` ### Segnale di duplicato (lo stato rimane `Approved`) ```json theme={null} { "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." } ] } ``` ## Risorse correlate * [Report di Ricerca facciale](https://docs.didit.me/it/core-technology/face-search/report-face-search.md) — formato completo della risposta * [Riferimento API di Ricerca facciale](https://docs.didit.me/it/standalone-apis/face-search.md) — parametri di richiesta * [Avvisi di Confronto facciale](https://docs.didit.me/it/core-technology/id-verification/warnings-id-verification.md) — avvisi di confronto 1:1 tra selfie e documento (distinti dalla Ricerca facciale) * [Modelli di dati — Ricerca facciale](https://docs.didit.me/it/reference/data-models.md#ricerca-facciale) — schema canonico ### Tipi di avviso This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.