错误处理

Android SDK 的所有错误处理均集中在本节。onErrorAcessoBio 回调接收一个包含 code 和 description 的 ErrorBio 对象。

错误代码

代码	默认消息	触发时机	推荐处理方式
AUTH_FAILED	SDK 认证失败	SDK Key 无效或已过期	与 Onboarding 团队验证凭据
CAMERA_PERMISSION_DENIED	相机权限被拒绝	用户拒绝了相机权限	引导用户前往应用设置
LIVENESS_FAILED	活体检测失败	图像未通过活体验证	请求重新采集
NETWORK_ERROR	采集过程中发生网络错误	网络连接不稳定	请求重新连接
SDK_NOT_INITIALIZED	SDK 未初始化	在初始化之前调用了采集	确保在 Application/onCreate 中调用初始化

官方错误目录

上述代码涵盖 SDK 回调的主要错误。REST API 错误代码（HTTP 状态码系列）单独记录在 API 参考 > 错误代码。

处理回调

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 */
  }
}

生命周期回调

除 onErrorAcessoBio 外，SDK 还会触发：

• onUserClosedCameraManually() — 用户手动关闭了相机。
• onSystemClosedCameraTimeoutSession() — 会话因超时而过期。
• onSystemChangedTypeCameraTimeoutFaceInference() — 13 秒内未检测到人脸；SDK 切换至手动采集模式。