Erros e diagnóstico

Os códigos, de relance

Código	Emitido por	O que significa	O que fazer
`200`	Serviço	A análise rodou. Não é uma aprovação: verifique `message`, `id` e as validações do verso.	Aplicar a regra de decisão.
`400`	Serviço	Um problema com a captura ou com o vínculo: imagem pequena demais, não decodificável, sem documento, `relatedUuid` ruim.	Corrigir a captura ou o vínculo.
`401`	Gateway	Falta o `Api-Key` ou a chave não vale para este ambiente.	Verificar chave e ambiente.
`404`	Gateway	Rota inexistente ou método HTTP errado (um `GET /front` devolve 404, não 405). Também um template desconhecido no catálogo.	Verificar rota e método.
`422`	Serviço	Violação do contrato: `info` ausente, `image` ausente, corpo malformado. O erro ecoa a sua solicitação.	Corrigir o corpo.
`500`	Serviço	Um erro transitório — ou um determinístico causado pela sua solicitação (`relatedUuid` em `/front`).	Ver a seção dos 500.
`503`	Serviço	O motor de OCR está fora do ar.	Repetir mais tarde com backoff.

As mensagens de `400`

Mensagem	Causa
`Image is too small ...`	Abaixo de 480 × 480 (a mensagem informa altura × largura).
`Image is not a valid`	O base64 não decodifica para uma imagem.
`No document detected`	A captura não tem um documento reconhecível. Peça outra captura.
`relatedUuid or documentId is required`	`/back` sem `relatedUuid`. A mensagem engana: só `relatedUuid` vincula a transação; `documentId` não o substitui.
`Bad relatedUuid`	O `relatedUuid` não corresponde a uma frente registrada. Se acontecer imediatamente depois de uma frente bem-sucedida, espere um segundo e repita uma vez (atraso de replicação); se persistir, o valor está errado.
`Document is too close to the borders`	Com `strictBorderMode`: o documento está cortado. Peça outra captura.

Os corpos de erro se parecem com isto:

{
  "uuid": "0f3f4a51-...",
  "code": 400,
  "message": "No document detected"
}

O uuid de um corpo de erro é gerado na hora e não corresponde a nenhuma transação — não serve como relatedUuid e o suporte não consegue consultá-lo.

O 422 ecoa a sua solicitação inteira — imagem incluída

O campo detail[].input do erro de validação é o eco literal do que você enviou, imagem base64 incluída, então um 422 pode pesar tanto quanto a solicitação:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "info"],
      "msg": "Field required",
      "input": { "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...v9Un0ooqDE//2Q==" }
    }
  ]
}

Nunca registre corpos de erro crus. Um 422 logado persiste a foto do documento de uma pessoa real nos seus logs. Registre o código, a mensagem e o caminho do campo — nunca input.

Os erros do gateway: outro formato

O 401 e o 404 vêm do gateway, com 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"
}

{
  "code": 404,
  "message": "Template 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 `500`

Um 500 é determinístico e seu: enviar relatedUuid em /front. Ele se reproduz idêntico a cada tentativa — não repita; remova o campo. Qualquer outro 500 é transitório: repita com backoff, no máximo 2 vezes. O teste de determinismo é o de sempre: se a repetição devolve o erro idêntico, a causa é a sua solicitação. O healthCheck pode devolver 408 enquanto /version ainda responde "Service OK" — trate como um aviso de degradação, não como indisponibilidade. Um 503 significa que o motor de OCR está fora do ar: nada a corrigir do seu lado; repita mais tarde.

Se precisar abrir um chamado

Escreva para customer.support@vusecurity.com com:

Dado	Onde está
O `uuid` da transação	No corpo `200` de `/front` (também no cabeçalho `x-request-id`).
O ambiente	Homologação ou produção.
Data e hora aproximadas	Com fuso horário.
O código HTTP e a mensagem	Sem o `detail` de um `422`, que contém a imagem.

Proteção de dados: nunca anexe fotos de documentos nem corpos de resposta crus a um chamado, a menos que o suporte peça explicitamente por um canal seguro.

Voltar à introdução

A regra de decisão, os três identificadores e o mapa de endpoints do ID Analysis.

Comece aqui

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Os códigos, de relance

As mensagens de `400`

O 422 ecoa a sua solicitação inteira — imagem incluída

Os erros do gateway: outro formato

Os `500`

Se precisar abrir um chamado

Voltar à introdução

​Os códigos, de relance

​As mensagens de 400

​O 422 ecoa a sua solicitação inteira — imagem incluída

​Os erros do gateway: outro formato

​Os 500

​Se precisar abrir um chamado

Voltar à introdução

Os códigos, de relance

As mensagens de `400`

O 422 ecoa a sua solicitação inteira — imagem incluída

Os erros do gateway: outro formato

Os `500`

Se precisar abrir um chamado