Erros e diagnóstico

Tabela de códigos

Código	O que significa	De quem é o problema	Repetir?
`200`	Análise concluída. Leia `spoofing` para o veredito.	—	Não
`400`	A imagem não cumpre um requisito rígido.	Seu	Não
`401`	Api-key ausente, inválida ou de outro ambiente.	Seu	Não
`422` + `No Face Detected`	Nenhum rosto foi detectado na imagem.	Da captura	Não
`422` + `Bad request` e `detail[]`	O corpo da requisição não valida.	Seu	Não
`499`	O cliente encerrou a conexão.	Sua rede ou seu timeout	Sim
`500`	Erro do lado do serviço.	Depende — veja abaixo	Só se não for determinístico

200 não significa aprovado. Significa que a análise foi concluída. Uma tentativa de falsificação detectada também responde 200, com spoofing: true. A aprovação exige as duas condições: status === 200 && spoofing === false.

Os dois `422`

O mesmo código cobre dois problemas completamente distintos, com dois donos distintos. Distinga-os pela presença de detail, não pelo código HTTP.

{
  "code": 422,
  "spoofing": true,
  "message": "No Face Detected",
  "id": "89f3f57e-...",
  "info": "onboarding-12345",
  "date": "2026-08-20",
  "time": "16:57:09"
}

{
  "id": "4b3501fb-...",
  "code": 422,
  "message": "Bad request",
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "info"],
      "msg": "Input should be a valid string",
      "input": { "ref": "onboarding-12345" }
    }
  ]
}

Sem rosto é um problema de captura: peça uma foto nova com instruções concretas — rosto centralizado, boa luz, nada na frente. Não é um bug e não se resolve repetindo a mesma imagem. Note que esta resposta traz spoofing: true: se o seu código aprova por exclusão, aqui ele aprova alguém cujo rosto nem chegou a ver. Corpo inválido é um problema de código. detail[].loc diz exatamente qual campo está errado; no exemplo, info foi enviado como objeto quando o contrato pede uma cadeia. Resolve-se do seu lado e se reproduz sempre.

`400`: a imagem não cumpre um requisito rígido

{
  "code": 400,
  "message": "Image should be larger than [224, 224]",
  "id": "f77e49f1-...",
  "info": "onboarding-12345"
}

Valide as dimensões antes de chamar. É mais rápido, mais barato e permite pedir ao usuário uma nova captura sem esperar a ida e volta.

`401`: credenciais

{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

Note que este corpo usa statusCode, não code, e não traz id: é rejeitado antes de criar uma transação. Verifique se o cabeçalho se chama exatamente Api-Key e se a chave corresponde ao ambiente da URL base que você está usando. Misturar a chave de homologação com a URL de produção é a causa mais comum.

`500`: nem todos são do serviço

Um 500 parece um problema do provedor, mas na prática a maioria é provocada pela requisição: dos cinco corpos 500 observados em testes, quatro tinham origem no pedido — uma imagem que o decodificador não conseguia processar, um payload malformado. O teste confiável é o determinismo:

Repita a mesma requisição uma vez

Com o mesmo corpo, sem alterar nada.

Compare o erro

Se voltar o mesmo error, o problema está na sua requisição: revise a imagem e o payload. Se voltar diferente ou a chamada tiver êxito, foi transitório.

Se for determinístico, pare de repetir

Abra um chamado com o id e o corpo do erro. Repetir apenas adiciona carga.

Política de novas tentativas

const REPETIVEL = (status, body) =>
  status === 499 ||
  (status === 500 && !/image|payload/i.test(body?.error ?? ""));

// No máximo 2 tentativas, com backoff exponencial. Nunca sobre spoofing: true.

Nunca repita uma resposta 200 com spoofing: true. É um veredito, não uma falha. Uma nova tentativa que «conserta» uma rejeição está aprovando fraude.

Abrir um chamado

Escreva para customer.support@vusecurity.com com:

Dado	Por quê
O `id` da transação	É a chave com que o suporte encontra o caso. Sem ele não há busca possível.
O ambiente	Homologação e produção podem rodar versões diferentes.
O carimbo de tempo aproximado	Delimita a janela de logs a revisar.
O corpo completo da resposta	Com `code`, `message` e `errorMessage` exatamente como chegaram.

Não anexe a imagem original a menos que o suporte peça explicitamente e por um canal combinado: é um dado biométrico de uma pessoa real.

Voltar à introdução

A regra de decisão, os endpoints e a autenticação.

Comece aqui

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Tabela de códigos

Os dois `422`

`400`: a imagem não cumpre um requisito rígido

`401`: credenciais

`500`: nem todos são do serviço

Política de novas tentativas

Abrir um chamado

Voltar à introdução

​Tabela de códigos

​Os dois 422

​400: a imagem não cumpre um requisito rígido

​401: credenciais

​500: nem todos são do serviço

​Política de novas tentativas

​Abrir um chamado

Voltar à introdução

Tabela de códigos

Os dois `422`

`400`: a imagem não cumpre um requisito rígido

`401`: credenciais

`500`: nem todos são do serviço

Política de novas tentativas

Abrir um chamado