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

Visão geral

O Face Search emite um pequeno conjunto de avisos para que sua equipe saiba por que uma busca retornou Approved ou Declined. Os avisos são retornados no array face_search.warnings[] da resposta de POST /v3/face-search/ (consulte o relatório do Face Search). Os avisos aqui têm um formato reduzido em comparação com os avisos do fluxo de verificação (workflow): não há node_id. O contrato de resposta documentado declara cinco campos (risk, additional_data, log_type, short_description, long_description), e o payload em tempo de execução traz também feature, que é sempre "LIVENESS" neste endpoint.

Avisos gerados

Risco	Causa	Severidade (`log_type`)	Afeta o status	Correção recomendada
`FACE_IN_BLOCKLIST`	A imagem de busca correspondeu a um rosto da lista de bloqueio facial da sua aplicação acima da faixa de similaridade de alta confiança.	`error`	Força `Declined`.	Rejeite o usuário. Investigue a sessão vinculada por meio de `additional_data.blocklisted_session_id`.
`POSSIBLE_FACE_IN_BLOCKLIST`	Um rosto da lista de bloqueio correspondeu dentro da faixa de similaridade “possível”, inferior à faixa de alta confiança.	`error`	Força `Declined` na API de busca facial independente (mais rigorosa que a verificação de prova de vida do fluxo, que envia esse risco para revisão).	Revisão manual. Confirme a correspondência com a evidência original da lista de bloqueio antes de agir.
`MULTIPLE_FACES_DETECTED`	Mais de um rosto foi encontrado na imagem de busca enviada. A busca ainda é executada, usando o maior rosto detectado.	`warning`	Nenhum: nunca recusa por si só.	Capture novamente com uma única pessoa no enquadramento se o maior rosto não for o desejado.
`DUPLICATED_FACE`	O rosto correspondeu, acima da faixa de alta confiança, a um rosto de uma sessão aprovada ou a um rosto importado de perfil de usuário. O endpoint avulso não exclui sessões com o mesmo `vendor_data`, então um usuário recorrente corresponde às próprias sessões anteriores.	`information`	Nenhum: duplicatas são exibidas como sinal, não como recusas.	Investigue a sessão vinculada por meio de `additional_data.duplicated_session_id`. Decida do seu lado se vai bloquear ou mesclar as contas.
`POSSIBLE_DUPLICATED_FACE`	Igual a `DUPLICATED_FACE`, mas a similaridade fica na faixa “possível”, inferior, em vez da faixa de alta confiança.	`information`	Nenhum.	Revisão manual antes de tratar os dois registros como a mesma pessoa.

Gerado por: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); derivação do status: get_face_search_status (apis/views/face_search.py:242-248), que recusa apenas nos dois riscos de lista de bloqueio. Regras de emissão que valem a pena conhecer:

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

Textos exatos 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 pode 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 pode ser verificado.
`DUPLICATED_FACE`	Rosto duplicado de outra sessão aprovada	O sistema identificou um rosto duplicado de outra sessão aprovada, o que exige 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, o que exige investigação adicional.
`MULTIPLE_FACES_DETECTED`	Vários rostos detectados	Vários rostos foram detectados na imagem de prova de vida. O sistema usa o maior rosto para a verificação de prova de vida e a comparação facial, mas a presença de vários rostos pode exigir revisão adicional.

Validação da imagem de busca

Quando nenhum rosto é detectado em user_image, a API rejeita a requisição com HTTP 400 e {"error": "No face detected in the image"} antes de montar um objeto face_search; por isso, um aviso NO_FACE_DETECTED nunca aparece em uma resposta bem-sucedida da Busca facial. Isso é retornado como uma string error de nível superior, e não em warnings[].

Configurações ajustáveis

As faixas de similaridade que separam correspondências confirmadas (FACE_IN_BLOCKLIST, DUPLICATED_FACE) de correspondências possíveis (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) são fixas internamente: o ajuste de limiar por aplicação vale para a verificação de prova de vida do fluxo, não para este endpoint. As opções que você controla por requisição são:

search_type (most_similar, padrão | blocklisted_or_approved): most_similar classifica todos os rostos cadastrados por similaridade; blocklisted_or_approved restringe os candidatos a rostos da lista de bloqueio, rostos da lista de permissão, rostos de sessões aprovadas e rostos importados de perfis de usuário, classificando primeiro as entradas da lista de bloqueio.
save_api_request (padrão true): persiste a chamada como uma sessão do tipo API e cadastra o rosto pesquisado no seu índice de busca facial. Rostos cadastrados por chamadas de Busca facial são excluídos de resultados futuros da Busca facial. Defina como false para consultar sem armazenar nem cadastrar.
rotate_image (padrão false): testa rotações de 90 graus e mantém a orientação com a melhor detecção de rosto; ú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 duplicidade (o status continua `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."
    }
  ]
}

Relacionados

Relatório de Busca facial: formato completo da resposta
Referência da API de Busca facial: parâmetros da requisição
Avisos de Correspondência facial: avisos da comparação 1:1 entre selfie e documento (separados da Busca facial)
Modelos de dados: Busca facial: esquema canônico

Autenticação

Verificação

Monitoramento

Plataforma

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

Visão geral

Avisos gerados

Textos exatos dos avisos

Validação da imagem de busca

Configurações ajustáveis

Exemplos

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

Sinal de duplicidade (o status continua `Approved`)

Relacionados

Tipos de aviso

​Visão geral

​Avisos gerados

​Textos exatos dos avisos

​Validação da imagem de busca

​Configurações ajustáveis

​Exemplos

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

​Sinal de duplicidade (o status continua Approved)

​Relacionados

​Tipos de aviso

Visão geral

Avisos gerados

Textos exatos dos avisos

Validação da imagem de busca

Configurações ajustáveis

Exemplos

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

Sinal de duplicidade (o status continua `Approved`)

Relacionados

Tipos de aviso