Erros e diagnóstico

Os códigos, de relance

Código	Emitido por	O que significa	O que fazer
`200`	Serviço	A operação rodou. Não implica match nem boa qualidade: avalie `biometric` e `inferenceConfidence`.	Aplicar a regra de decisão.
`400`	Serviço	Um problema com uma imagem ou operação específica: sem rosto, pequena demais, base64 inválido, operação inexistente.	Corrigir a imagem ou operação indicada. Não repetir igual.
`401`	Gateway	Falta o cabeçalho `Api-Key` ou a chave não vale para este ambiente.	Verificar chave e ambiente.
`404`	Gateway	Rota inexistente ou método errado (um `GET /inference` devolve 404, não 405).	Verificar rota e método.
`422`	Serviço	O corpo não é JSON válido, não é um objeto, ou `info` viola o formato.	Corrigir o corpo.
`500`	Serviço	Ou um erro transitório, ou a sua solicitação: `images` ausente ou `operations` desalinhado. Corpo em texto puro.	Ver a seção dos 500.

Os `400`: um único erro, com índice

O corpo do 400 aponta a imagem culpada com imageNumber (base 0):

{
  "id": "7be2f9a1-...",
  "code": 400,
  "message": "Face not found",
  "imageNumber": 1
}

Mensagem	Causa
`Face not found`	Nenhum rosto foi detectado na imagem indicada. Peça outra captura.
`Image is too small`	A imagem está abaixo do mínimo rígido de 160 × 160 px.
`Image is not valid`	O conteúdo de `images[i]` não é base64 decodificável.
`Operation is not valid`	Um nome de operação não existe, ou você enviou `operations` como lista simples em vez de lista de listas.

Uma imagem ruim aborta o lote inteiro. Se você envia 4 imagens e a terceira não tem rosto, recebe um único 400 com imageNumber: 2 e nenhum resultado — não há resultados parciais. Se o seu fluxo tolera falhas por imagem, envie uma solicitação por imagem.

Os `500` vêm em texto puro

Dois erros de solicitação não devolvem um 400 arrumado, mas um 500 com o corpo literal Internal Server Error — não é JSON:

Omitir o campo images.
Enviar uma lista operations mais curta que images.

O seu cliente HTTP não deve assumir que toda resposta é JSON: envolva o parsing e trate a falha de parsing como erro, nunca como aprovação. Como distinguir um 500 transitório de um seu: repita uma vez com backoff. Se voltar idêntico, é determinístico — a causa é a sua solicitação; valide images e o alinhamento de operations no seu código e pare de repetir.

Os erros do gateway: outro formato

O 401 e o 404 não são emitidos pelo serviço, mas pelo gateway, e o corpo deles tem outro formato (statusCode em vez de code):

{
  "statusCode": 401,
  "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
}

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

{
  "statusCode": 404,
  "message": "Resource not found"
}

Um 401 com uma chave que «sempre funcionou» costuma ser mistura de ambientes: a chave de homologação contra a URL de produção ou vice-versa. Verifique o par URL + chave antes de escalar.

Os `422`: violações do contrato

Corpo não-JSON, corpo que não é um objeto, ou info fora do intervalo (2–256 caracteres) devolvem 422 com o detalhe campo a campo em detail. São erros de programação, não de dados: corrija-os em desenvolvimento, não os trate em produção.

Política de novas tentativas

Erro	Repetir?
`500` esporádico (não se repete idêntico)	Sim, com backoff, no máximo 2.
`500` determinístico	Não: corrigir a solicitação.
`400` / `401` / `404` / `422`	Não: corrigir imagem, credencial, rota ou corpo.
No-match (`200` com pontuação baixa)	Nunca com a mesma imagem: o resultado é determinístico. Peça outra captura.
`spoofing: true`	Nunca com a mesma imagem.

Se precisar abrir um chamado

Escreva para customer.support@vusecurity.com com:

Dado	Onde está
O `id` da transação	No corpo da resposta (também presente nos `400`).
O ambiente	Homologação ou produção.
Data e hora aproximadas	Com fuso horário.
O código HTTP e a mensagem	Sem anexar imagens base64 nem corpos crus com dados pessoais.

Voltar à introdução

A regra de decisão, os endpoints e o mapa de operações do Face Analysis.

Comece aqui

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Os códigos, de relance

Os `400`: um único erro, com índice

Os `500` vêm em texto puro

Os erros do gateway: outro formato

Os `422`: violações do contrato

Política de novas tentativas

Se precisar abrir um chamado

Voltar à introdução

​Os códigos, de relance

​Os 400: um único erro, com índice

​Os 500 vêm em texto puro

​Os erros do gateway: outro formato

​Os 422: violações do contrato

​Política de novas tentativas

​Se precisar abrir um chamado

Voltar à introdução

Os códigos, de relance

Os `400`: um único erro, com índice

Os `500` vêm em texto puro

Os erros do gateway: outro formato

Os `422`: violações do contrato

Política de novas tentativas

Se precisar abrir um chamado