Documentação

Erros da API

Respostas de erro dos endpoints REST. Para erros no callback onError do SDK, veja também Resultado e erros (SDK).

Formato padrão

Erros HTTP retornam status 4xx ou 5xx com corpo JSON:

{
  "error": {
    "code": "ROSTO_NAO_DETECTADO",
    "message": "Nenhum rosto detectado na imagem.",
    "details": {
      "field": "compareImage"
    }
  }
}

Mensagens em português. O campo details é opcional e varia por código.

Erros de autenticação e rede também aparecem no callback onError do SDK com os mesmos códigos. Veja Resultado e erros (SDK).

Autenticação e quota

Código	Significado
`API_KEY_AUSENTE`	Cabeçalho `Authorization` ausente.
`API_KEY_INVALIDA`	Chave inválida ou não encontrada.
`APIKEY_REVOGADA`	Chave revogada no dashboard.
`ORIGEM_NAO_AUTORIZADA`	Domínio da requisição não está na lista de domínios autorizados da chave (requisições do navegador).

Imagens e comparação

Comuns em POST /v1/compare:

Código	Quando ocorre
`IMAGEM_REFERENCIA_INACESSIVEL`	URL da referência inacessível, timeout ou HTTP de erro.
`IMAGEM_COMPARACAO_INACESSIVEL`	URL da imagem de comparação inacessível.
`ROSTO_NAO_DETECTADO`	Nenhum rosto na imagem. Em `POST /v1/compare`, `error.details.field` indica `referenceImage` ou `compareImage`.
`MULTIPLOS_ROSTOS_DETECTADOS`	Mais de um rosto — `error.details.faceCount` traz a quantidade.
`IMAGEM_FORMATO_INVALIDA`	Arquivo não é JPEG/PNG válido ou foi rejeitado pelo provedor.

Respostas de sucesso por endpoint

POST /v1/compare

200 OK

{
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "matched": true,
  "similarity": 97.2,
  "timestamp": "2026-07-17T14:00:00.000Z"
}

matched é true quando similarity atinge o limiar configurado (padrão 90). Não inclui liveness nem selfieBase64.