Face Search 1:N: avvisi e codici di errore

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). 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`)

{
  "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`)

{
  "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 — formato completo della risposta
Riferimento API di Ricerca facciale — parametri di richiesta
Avvisi di Confronto facciale — avvisi di confronto 1:1 tra selfie e documento (distinti dalla Ricerca facciale)
Modelli di dati — Ricerca facciale — schema canonico

Autenticazione

Verifica

Monitoraggio

Piattaforma

Face Search 1:N: avvisi e codici di errore

Panoramica

Avvisi generati

Stringhe esatte degli avvisi

Controllo dell’immagine di ricerca

Impostazioni configurabili

Esempi

Corrispondenza con la blocklist (forza `Declined`)

Segnale di duplicato (lo stato rimane `Approved`)

Risorse correlate

Tipi di avviso

​Panoramica

​Avvisi generati

​Stringhe esatte degli avvisi

​Controllo dell’immagine di ricerca

​Impostazioni configurabili

​Esempi

​Corrispondenza con la blocklist (forza Declined)

​Segnale di duplicato (lo stato rimane Approved)

​Risorse correlate

​Tipi di avviso

Panoramica

Avvisi generati

Stringhe esatte degli avvisi

Controllo dell’immagine di ricerca

Impostazioni configurabili

Esempi

Corrispondenza con la blocklist (forza `Declined`)

Segnale di duplicato (lo stato rimane `Approved`)

Risorse correlate

Tipi di avviso