ZOLOZZOLOZDOCS

客户端错误

错误分类

客户端错误包括以下两种：

  • SDK错误码：通过SDK API返回，用于标识SDK的返回状态。
  • SDK错误弹窗：在SDK运行过程中通过弹窗提示的错误。

SDK错误码

  • SDK回调结果
    对于客户端SDK信息，您只需要关注SDK回调结果，SDK回调结果包括完成和中断两种。
    • 如果SDK回调结果为完成，则可以调用服务端API（例如checkresult）获取业务状态和结果。
    • 如果SDK回调结果为中断，则客户端上会显示对应的提示弹窗（例如网络错误、超时等）。SDK还将返回一个以Z开头且包含四位数字的代码，用户可以选择“Quit”或“Got it”（具体文案由用户自定义），或其他操作来关闭SDK。然后根据业务需求进行后续的流程，例如引导用户重试或等待人工审核。
  • SDK集成处理
    • 开发人员集成过程中如果SDK报错，可参考SDK返回码表排查错误。表格中仅包含集成过程中常见的返回码。
    • 如果您已成功集成SDK且整个过程运行顺利，则可以忽略SDK返回码，该代码仅用于ZOLOZ技术支持团队在收到客户反馈时进行进一步故障排查。

SDK回调结果

SDK回调结果包括SDK采集完成和SDK采集中断两种，以下是Android和iOS SDK的回调内容。

Android

iOS

startWithRequest: completeCallback: interruptCallback:

SDK采集完成

当SDK采集完成，客户端流程结束后，开发人员可以调用服务端的checkresult API查看业务状态和结果。

SDK采集中断

SDK采集中断并退出，该回调结果表示操作已经结束。

当SDK采集中断时，服务端的状态分为以下两种情况：

  • 如果是用户主动取消（单击“Quit”或“Got it”），服务端会收到通知且服务端的状态会变成取消。
  • 如果是后台终止或系统异常导致，SDK感知不到且不会通知服务端，此时服务端的状态仍将处于处理中，SDK回调信息与服务端接口状态并不冲突。

当SDK采集中断时，客户端上会显示对应的提示弹窗（例如网络错误、超时等），用户必须选择“Quit”或“Got it”，或其他操作来关闭SDK；同时客户可以根据提示弹窗调整测试方法，关于提示弹窗的详细说明，请参见错误弹窗说明。

SDK返回码

请不要依赖SDK返回码设计业务处理逻辑，SDK返回码仅在客户端出现异常时，用于排查问题或进行数据分析。

Z10XX

返回码

描述

Z1000

  • Android：算法模型错误或系统错误。
  • iOS：服务端下发的参数解析异常（bioType错误）。

Z1001

客户端算法初始化失败

Z1002

无法启动相机

Z1003

硬件（CPU）不支持

Z1004

操作系统版本太低

Z1005

单次刷脸超时

Z1006

重试次数超过阈值

Z1008

用户主动退出刷脸

Z1009

切换后台运行时退出

Z1010

  • Android：内部反射异常或找不到对应的页面。
  • iOS：zimid为空。

Z1012

网络错误

Z1013

活体检测不通过

Z1016

用户点击了重试弹框的退出按钮

Z1018

没有前置摄像头

Z1019

没有摄像头的访问权限

Z1020

相机打开失败

Z1021

摄像头没有图像流

Z1022

验证中断，内部错误。

Z1024

上一次认证未结束

Z2XXX

返回码

描述

Z2000

系统错误

Z2001

Android：

  • 没有前置摄像头
  • 摄像头初始化失败
  • 没有摄像头的访问权限

iOS：

  • 没有相机权限
  • 客户端算法加载失败

Z2002

用户主动退出

Z2003

网络连接异常

Z2006

重试次数超过阈值

Z2007

防伪检测不通过，用户主动退出。

Z2341

未检测到证件

Z50XX

返回码

描述

Z5001

请求协议错误

Z70XX

返回码

描述

Z7001

网络连接异常

Z7002

用户主动退出

Z7003

eKYC调用回调onComplete，结果为Success（仅适用于Android）。

Z7005

eKYC调用回调onComplete，结果为Pending（仅适用于Android）。

Z7010

clientCfg返回值不正确

Z7011

  • 上下文为空（Android）
  • 视图控制器为空（iOS）

Z7012

客户端配置为空

Z7013

FLOW_TYPE为空

Z7014

RPC或uiconfig配置错误

Z7015

读取文件失败

Z7016

没有网络服务配置文件（仅适用于Android）

Z7017

反射失败（仅适用于Android）

Z7018

zimid为空

Z7019

bizDataKey的值为空

Z7020

zlzconfig中的Web Task的URL为空

Z7021

当前任务不是Web Task

Z7022

RPC错误（非网络问题）

Z7023

H5关键参数校验失败

Z7024

具体问题具体分析

Z7025

Native Task中传入的zimid为空

Z7026

Web Task中传入的URL为空

Z7027

在配置中找不到URL模式

Z7028

任务索引不正确

Z7029

任务类型不正确，目前只支持nativeTask、webTask、serverTask。

Z7030

服务器任务名称不正确

Z7031

  • zlzConfig的authType参数不合法
  • 客户端配置不正确

Z7032

Native Task中传入的zimInitResp为空

Z7033

Web Task结果处理错误

Z7035

证件或人脸采集成功

Z7075

相机初始化失败

Z7076

相机打开失败

Z7077

算法初始化失败，模型文件有问题，阻断用户操作。

Z7078

服务端向客户端返回了一个无法识别的返回码

Z90XX

返回码

描述

Z9003

ZOLOZ CONNECT识别成功

Z9004

ZOLOZ CONNECT识别失败

SDK错误弹窗

客户端错误弹窗对在线的C端用户可见，开发人员只需要填写相应的文案即可，不需要处理每个弹窗的业务逻辑。

自定义错误弹窗

您可以在UI配置平台查看所有弹窗，并自定义配置每个弹窗的标题、文案和按钮内容。

错误弹窗说明

弹窗类型

默认标题

默认文案

出现原因

默认按钮文案

系统错误

System error

Sorry, a system error has occured. Please try again later.

Got it：用户单击按钮退出SDK。

网络错误

Internet connection failure

Please check your internet connection and try again.

网络连接失败

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试连接网络，SDK不退出。

开启摄像头失败

No camera permission

Please allow the application to access your camera, or refresh and try again.

未授权相机权限

  • Quit：用户单击按钮退出SDK。
  • Go to settings：用户单击按钮授权相机权限，SDK不退出。

已达到重试限制

Too many attempts

You have reached the maximum number of attempts. Please try again later.

用户进行了多次证件扫描或刷脸，重试次数已超出设置的限制。

Quit：用户单击按钮退出SDK。

用户退出ID Recognition

Are you sure you want to quit?

Please make sure your ID is clear and non-reflective for easy scanning.

用户单击退出证件扫描界面

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

证件已过期

ID expired

Make sure your ID is not expired.

证件已过期

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

证件上未检测到人脸

The portrait is incomplete

The portrait in the document is blurry or incomplete, please take a clear photo.

证件上未检测到人脸

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

证件过度曝光

ID over exposure

Please adjust the lighting to avoid over exposure.

证件过度曝光

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

证件不清晰

ID not clear

Please make sure your ID is fully visible, glare-free and not blurry.

证件模糊未通过质量检测

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

证件不完整

ID not complete

Please make sure your ID is fully visible, glare-free and not blurry.

采集的证件不完整，未通过质量检测。

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

证件错误

Incorrect ID type detected

Make sure you are using the required type of ID.

采集的证件和要求的证件类型不一致

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

未知证件

Incorrect ID type detected

Make sure you are using the required type of ID.

未知的证件类型，采集的证件不是所需的证件类型。

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

未检测到证件

No ID detected

Please align your ID with the frame before taking a photo.

没有采集到任何证件

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试扫描证件，SDK不退出。

用户退出人脸识别

Are you sure you want to quit?

Please face the camera directly for easy capturing.

用户单击退出人脸采集界面

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试刷脸，SDK不退出。

人脸识别失败

Face verification failed

Please face the phone camera directly and ensure that your face is bright and clear.

人脸采集失败。活体人脸与证件脸比对达不到通过的阈值，用户需重新采集人脸。该错误很少发生。

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试刷脸，SDK不退出。

人脸识别超时

Operation Timeout

Please face the camera directly for easy capturing.

刷脸超时，在设定的时间范围内未检测到人脸。

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试刷脸，SDK不退出。

人脸识别中断

Face verification interruption

Please face the camera directly for easy capturing.

人脸采集过程中可能因后台切换App等原因导致中断，用户再次返回App时只能选择重试或退出。

  • Quit：用户单击按钮退出SDK。
  • Retry：用户单击按钮并再次尝试刷脸，SDK不退出。

设备不支持

Face verification is not supported on this device.

不支持该设备。该错误很少发生。

Got it：用户单击按钮退出SDK。

人脸采集相机初始化失败

Face verification is not supported on this device.

由于硬件问题，设备无法打开相机。该错误很少发生。

Got it：用户单击按钮退出SDK。

证件采集相机初始化失败

Document capture is not supported on this device.

由于硬件问题，设备无法打开相机。该错误很少发生。

Got it：用户单击按钮退出SDK。