Pesquisa facial 1:N: avisos e códigos de erro

Visão geral

A Pesquisa facial emite um pequeno conjunto de avisos para que a sua equipa possa perceber por que razão uma pesquisa devolveu Approved ou Declined. Os avisos são devolvidos no array face_search.warnings[] da resposta a POST /v3/face-search/ (consulte o relatório da Pesquisa facial). Os avisos aqui utilizam um formato reduzido em comparação com os avisos de fluxo: não existe node_id. O contrato de resposta documentado declara cinco campos — risk, additional_data, log_type, short_description, long_description — e o payload de execução inclui adicionalmente feature, que é sempre "LIVENESS" neste endpoint.

Avisos produzidos

Risco	Causa	Gravidade (`log_type`)	Afeta o estado	Mitigação recomendada
`FACE_IN_BLOCKLIST`	A imagem de pesquisa correspondeu a um rosto na lista de bloqueio de rostos da sua aplicação acima do intervalo de similaridade de alta confiança.	`error`	Força `Declined`.	Rejeite o utilizador. Investigue a sessão associada através de `additional_data.blocklisted_session_id`.
`POSSIBLE_FACE_IN_BLOCKLIST`	Um rosto na lista de bloqueio correspondeu dentro do intervalo de similaridade inferior de “possível”, abaixo do intervalo de alta confiança.	`error`	Força `Declined` na API autónoma de Pesquisa facial (mais rigorosa do que a verificação de prova de vida do fluxo, que envia este risco para análise).	Revisão manual. Confirme a correspondência com a evidência original da lista de bloqueio antes de agir.
`MULTIPLE_FACES_DETECTED`	Foi detetado mais do que um rosto na imagem de pesquisa enviada. A pesquisa continua a ser executada, utilizando o maior rosto detetado.	`warning`	Nenhum — nunca recusa por si só.	Volte a capturar com um único sujeito no enquadramento se o maior rosto não for o pretendido.
`DUPLICATED_FACE`	O rosto correspondeu, acima do intervalo de alta confiança, a um rosto de uma sessão aprovada ou a um rosto de perfil de utilizador importado. O endpoint autónomo não exclui sessões com o mesmo `vendor_data`, pelo que um utilizador recorrente corresponde às suas próprias sessões anteriores.	`information`	Nenhum — os duplicados são apresentados como sinal, não como recusas.	Investigue a sessão associada através de `additional_data.duplicated_session_id`. Decida se pretende bloquear ou fundir contas do seu lado.
`POSSIBLE_DUPLICATED_FACE`	O mesmo que `DUPLICATED_FACE`, mas a similaridade situa-se no intervalo inferior de “possível” em vez do intervalo de alta confiança.	`information`	Nenhum.	Revisão manual antes de tratar os dois registos como a mesma pessoa.

Produtor: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); derivação de estado: get_face_search_status (apis/views/face_search.py:242-248), que recusa apenas para os dois riscos de lista de bloqueio. Regras de emissão que convém conhecer:

A lista de bloqueio tem precedência sobre os duplicados. Uma correspondência confirmada na lista de bloqueio suprime DUPLICATED_FACE, e uma possível correspondência na lista de bloqueio suprime POSSIBLE_DUPLICATED_FACE — nunca recebe ambos os membros de um par para o mesmo intervalo de confiança.
additional_data referencia apenas o primeiro rosto correspondente, mesmo quando matches[] contém vários. Os avisos de lista de bloqueio contêm {blocklisted_session_id, blocklisted_session_number, api_service}; os avisos de duplicado contêm {duplicated_session_id, duplicated_session_number, api_service}; MULTIPLE_FACES_DETECTED contém null. O valor de api_service está em maiúsculas (por exemplo, PASSIVE_LIVENESS) ou null para sessões de fluxo.
Rostos na lista de permissões suprimem avisos de duplicado — uma correspondência de alta confiança na lista de permissões anula DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE (nunca anula avisos de lista de bloqueio).

Strings exatas dos avisos

Risco	`short_description`	`long_description`
`FACE_IN_BLOCKLIST`	Rosto na lista de bloqueio	O sistema identificou um rosto na lista de bloqueio, o que significa que o rosto não tem permissão para ser verificado.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possível rosto na lista de bloqueio	O sistema identificou um possível rosto na lista de bloqueio, o que significa que o rosto não tem permissão para ser verificado.
`DUPLICATED_FACE`	Rosto duplicado de outra sessão aprovada	O sistema identificou um rosto duplicado de outra sessão aprovada, exigindo investigação adicional.
`POSSIBLE_DUPLICATED_FACE`	Possível rosto duplicado de outra sessão aprovada	O sistema identificou um possível rosto duplicado de outra sessão aprovada, exigindo investigação adicional.
`MULTIPLE_FACES_DETECTED`	Múltiplos rostos detetados	Foram detetados múltiplos rostos na imagem de prova de vida. O sistema utiliza o maior rosto para a verificação de prova de vida e comparação facial, mas a presença de múltiplos rostos pode exigir uma revisão adicional.

Validação da imagem de pesquisa

Quando não é detetado nenhum rosto em user_image, a API rejeita o pedido com o código HTTP 400 e {"error": "No face detected in the image"} antes de um objeto face_search ser construído — pelo que um aviso NO_FACE_DETECTED nunca aparece numa resposta bem-sucedida da Pesquisa facial. Isto é devolvido como uma string de error de nível superior, e não em warnings[].

Definições configuráveis

Os intervalos de similaridade que separam correspondências confirmadas (FACE_IN_BLOCKLIST, DUPLICATED_FACE) de possíveis correspondências (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) são fixos internamente — o ajuste de limiares por aplicação aplica-se à verificação de prova de vida do fluxo, não a este endpoint. Os parâmetros que controla por pedido são:

search_type (most_similar, predefinição | blocklisted_or_approved) — most_similar classifica cada rosto registado por similaridade; blocklisted_or_approved restringe os candidatos a rostos na lista de bloqueio, rostos na lista de permissões, rostos de sessões aprovadas e rostos de perfis de utilizador importados, classificando as entradas na lista de bloqueio em primeiro lugar.
save_api_request (predefinição true) — persiste a chamada como uma sessão do tipo API e regista o rosto pesquisado no seu índice de pesquisa facial. Os rostos registados por chamadas de Pesquisa facial são excluídos de resultados futuros da Pesquisa facial. Defina como false para consultar sem armazenar ou registar.
rotate_image (predefinição false) — tenta rotações de 90 graus e mantém a orientação com a melhor deteção facial; útil quando a orientação EXIF está ausente.

Exemplos

Correspondência na lista de bloqueio (força `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."
    }
  ]
}

Sinal de duplicado (o estado permanece `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."
    }
  ]
}

Relacionado

Relatório de Pesquisa facial — formato completo da resposta
Referência da API de Pesquisa facial — parâmetros do pedido
Avisos de Correspondência facial — avisos de correspondência 1:1 entre selfie e documento (separados da Pesquisa facial)
Modelos de dados — Pesquisa facial — esquema canónico

Autenticação

Verificação

Monitorização

Plataforma

Pesquisa facial 1:N: avisos e códigos de erro

Visão geral

Avisos produzidos

Strings exatas dos avisos

Validação da imagem de pesquisa

Definições configuráveis

Exemplos

Correspondência na lista de bloqueio (força `Declined`)

Sinal de duplicado (o estado permanece `Approved`)

Relacionado

Tipos de aviso

​Visão geral

​Avisos produzidos

​Strings exatas dos avisos

​Validação da imagem de pesquisa

​Definições configuráveis

​Exemplos

​Correspondência na lista de bloqueio (força Declined)

​Sinal de duplicado (o estado permanece Approved)

​Relacionado

​Tipos de aviso

Visão geral

Avisos produzidos

Strings exatas dos avisos

Validação da imagem de pesquisa

Definições configuráveis

Exemplos

Correspondência na lista de bloqueio (força `Declined`)

Sinal de duplicado (o estado permanece `Approved`)

Relacionado

Tipos de aviso