Códigos de retorno

Toda resposta da API traz um objeto transaction com o desfecho da operação. Ele diz por que uma validação ou um cadastro não passou — a diferença entre um rosto que o servidor não conseguiu ler e uma credencial inválida, por exemplo, muda completamente o que a aplicação deve fazer em seguida.

{
  "isSuccess": false,
  "transaction": {
    "code": 10,
    "message": "Liveness check failed",
    "isSuccess": false
  }
}

O campo isSuccess do objeto repete o desfecho do código: apenas o 1 é positivo.

Tabela

Código	Mensagem	Quando acontece	O que fazer
1	Success	A operação foi concluída.	—
2	UnAuthorized	Credencial ausente, inválida ou expirada: UUID, API Key, API Secret ou token da sessão.	Confira as credenciais da integração. Repetir a chamada com as mesmas não resolve.
3	Face not found	O servidor não encontrou um rosto legível no quadro recebido.	Repita a leitura com o rosto enquadrado, de frente e com iluminação suficiente.
4	Invalid document	O documento informado no cadastro não é válido.	Corrija o documento e o tipo (CPF, RG ou CNH).
5	Document already added	Já existe uma pessoa cadastrada com esse documento.	Use a atualização em vez do cadastro, ou confira se é a mesma pessoa.
6	Name cannot be empty	O nome não foi informado.	Envie o nome da pessoa.
7	Entity not found with document	A atualização apontou para um documento que não está na base.	Confira o identificador da pessoa antes de atualizar.
8	Face already added	O rosto enviado já pertence a alguém cadastrado.	Verifique se a pessoa já existe na base com outro documento.
9	Not Mach	Na verificação contra uma pessoa específica, o rosto não corresponde.	É um desfecho legítimo: trate como "não é a mesma pessoa".
10	Liveness check failed	A prova de vida foi reprovada — vivacidade abaixo do limite ou condições da captura.	Oriente a pessoa a repetir numa posição e iluminação melhores.
11	Session binding failed	A sessão da leitura venceu, já tinha sido usada ou não corresponde ao aparelho.	Inicie uma validação nova. Reenviar o mesmo quadro não passa.
12	Access not allowed at this point	A pessoa foi reconhecida, mas não tem liberação para este ponto de acesso.	Não é "não cadastrado": trate como acesso negado e, se for o caso, revise as permissões do ponto.
13	Monthly validation limit reached	O limite de validações do plano foi atingido no mês corrente.	Aguarde a virada do mês ou mude de plano.
14	Enrolled people limit reached	A base chegou ao limite de pessoas do plano.	Remova cadastros que não usa mais ou mude de plano.
0	Message not available	A resposta veio sem um código reconhecido.	Trate como falha genérica e registre a resposta inteira para análise.

Os códigos 13 e 14 são separados de propósito: validações esgotadas se resolvem com o tempo ou com upgrade; base cheia exige liberar espaço. Um código único faria a aplicação adivinhar qual dos dois aconteceu.

Onde o código aparece

Plataforma	Como ler
API REST	transaction.code na resposta
Android	getTransactionCode() no resultado
iOS	transactionCode no resultado
Web	transactionCode no resultado
Flutter	apenas a mensagem, em message
React Native	apenas a mensagem, em message
.NET MAUI	apenas a mensagem, em Message

Nos três últimos, o número não atravessa a ponte para o código da aplicação: a descrição do desfecho chega em message, e é por ela que a tela deve se orientar.

Tratando o retorno

Uma recusa não é uma exceção. Em todos os SDKs, reprovação, erro e cancelamento chegam no próprio resultado — a chamada não lança. O desenho recomendado é:

1. Cancelamento primeiro: a pessoa fechou a tela, e não há o que informar.
2. Sucesso: siga o fluxo.
3. Qualquer outro caso: mostre a descrição que veio em message e decida pelo código, quando a plataforma o expõe.

Repetir automaticamente só faz sentido nos códigos de leitura — 3 e 10 —, e ainda assim com uma nova captura. Os demais pedem correção de dados, de credencial ou de plano, e tentar de novo devolve o mesmo resultado.