Tratamento de erros

Todo o tratamento de erros do SDK Android está centralizado nesta seção. O callback onErrorAcessoBio recebe um objeto ErrorBio com os campos code e description.

Códigos de erro

Código	Mensagem padrão	Quando ocorre	Tratamento recomendado
AUTH_FAILED	SDK authentication failed	SDK Key inválida ou expirada	Valide as credenciais com o time de Onboarding
CAMERA_PERMISSION_DENIED	Camera permission denied	Usuário negou a permissão de câmera	Direcione o usuário para as configurações do app
LIVENESS_FAILED	Liveness check failed	A imagem não passou na validação de liveness	Solicite uma nova captura
NETWORK_ERROR	Network error during capture	Conectividade insuficiente	Solicite reconexão
SDK_NOT_INITIALIZED	SDK not initialized	Captura chamada antes da inicialização	Garanta que o init seja chamado em Application/onCreate

Códigos de erro do SDK

Os códigos acima cobrem os principais erros de callback do SDK. Os códigos de erro da REST API (famílias de status HTTP) estão documentados separadamente em Referência de API > Códigos de erro.

Tratando o callback

Kotlin

override fun onErrorAcessoBio(error: ErrorBio) {
  when (error.code) {
    "AUTH_FAILED" -> { /* handle authentication failure */ }
    "CAMERA_PERMISSION_DENIED" -> { /* redirect to app settings */ }
    "LIVENESS_FAILED" -> { /* prompt the user to try again */ }
    else -> { /* generic error handling */ }
  }
}

Java

@Override
public void onErrorAcessoBio(ErrorBio error) {
  switch (error.getCode()) {
    case "AUTH_FAILED": /* handle authentication failure */ break;
    case "CAMERA_PERMISSION_DENIED": /* redirect to app settings */ break;
    case "LIVENESS_FAILED": /* prompt the user to try again */ break;
    default: /* generic error handling */
  }
}

Callbacks de ciclo de vida

Além de onErrorAcessoBio, o SDK também dispara:

• onUserClosedCameraManually() — usuário fechou a câmera manualmente.
• onSystemClosedCameraTimeoutSession() — sessão expirada por timeout.
• onSystemChangedTypeCameraTimeoutFaceInference() — nenhum rosto detectado em 13 segundos; o SDK muda para captura manual.