> ## 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. # Busca facial 1:N: avisos e códigos de erro > Avisos da busca facial 1:N da Didit: rosto na lista de bloqueio, rostos duplicados, múltiplos rostos e imagens sem rosto detectável. ## 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](https://docs.didit.me/pt-br/core-technology/face-search/report-face-search.md)). 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`) ```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." } ] } ``` ### Sinal de duplicidade (o status continua `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." } ] } ``` ## Relacionados * [Relatório de Busca facial](https://docs.didit.me/pt-br/core-technology/face-search/report-face-search.md): formato completo da resposta * [Referência da API de Busca facial](https://docs.didit.me/pt-br/standalone-apis/face-search.md): parâmetros da requisição * [Avisos de Correspondência facial](https://docs.didit.me/pt-br/core-technology/id-verification/warnings-id-verification.md): avisos da comparação 1:1 entre selfie e documento (separados da Busca facial) * [Modelos de dados: Busca facial](https://docs.didit.me/pt-br/reference/data-models.md#busca-facial): esquema canônico ### Tipos de aviso This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.