客户端错误

错误分类

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

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

SDK错误码

对于客户端SDK,您只需要关注SDK的回调结果。SDK回调结果包括完成和中断两种。

  • 如果回调结果为完成,则可以调用服务端接口,例如checkresult获取结果和图片。
  • 如果回调结果为中断,则会向客户端显示一个弹窗警报(例如网络错误、超时等),用户可以选择"Quit"或"Got it"(具体文案由用户自定义),或其他操作来关闭交易。然后根据业务需求进行后续的流程,例如引导用户重试或等待人工审核。

当退出SDK时,除了回调结果之外,SDK还会返回一个代码,即以Z开头的四位数字。

  • 开发人员集成过程中如果SDK报错,可参考SDK返回码表排查错误。表格中仅包含集成过程中常见的错误码。
  • 如果您已成功集成SDK且整个过程运行顺利,则可以忽略这些代码。这些代码仅用作记录。

SDK回调结果

SDK回调结果包括完成和中断两种,以下分别是Android和iOS SDK的回调内容。

Android

iOS

startWithRequest: completeCallback: interruptCallback:

SDK完成

SDK采集和客户端处理完成后,您需要调用服务端的checkresult接口来查看业务状态和结果。

SDK中断

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

在SDK中断的情况下,服务器端的状态分为两种情况:

  • 如果用户取消(通过单击"Quit"或"Got it"),服务器将收到通知且服务器状态将更改为取消。
  • 在后台终止或系统异常的情况下,SDK将无法感知或通知服务器,此时服务端状态仍将处于处理中,SDK回调信息不会与服务端接口状态冲突。

如果SDK中断,则会向客户端显示相应的弹窗(例如网络错误、超时等),用户必须选择"Quit"或"Got it",或其他操作来关闭交易。因此,可以根据弹窗调整测试方法。关于每个弹窗的详细说明,请参见错误弹窗说明

SDK返回码

返回码

描述

Z7001

未连接到互联网

Z7002

用户主动退出

Z7010

eKYC ID为空

Z7011

  • 上下文为空(Android)
  • 视图控制器为空(iOS)

Z7012

客户端配置为空

Z7013

FLOW_TYPE为空

Z7014

没有配置文件

Z7015

读取文件失败

Z7016

没有网络服务配置文件(仅适用于Android)

Z7017

反射失败(仅适用于Android)

Z7018

zimid为空

Z7019

bizDataKey的值为空

Z7020

URL为空

Z7021

当前任务不是webtask

Z7022

RPC异常,网络问题除外

Z7023

H5关键参数校验失败

Z7024

具体问题具体分析

Z7025

zimid键为空

Z7026

URL格式为空

Z7027

在配置中找不到URL模式

Z7028

任务索引不正确

Z7029

任务类型不正确

Z7030

服务器任务名称不正确

Z7031

配置格式不正确

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 ID is not complete

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

在证件上未检测到人脸

"Quit"——用户单击按钮退出SDK

"Retry"——用户单击并再次尝试扫描证件;SDK不退出

证件过度曝光

The ID is not complete

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

证件过度曝光

"Quit"——用户单击按钮退出SDK

"Retry"——用户单击并再次尝试扫描证件;SDK不退出

证件不清晰

The ID is not complete

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

证件模糊未通过质量检测

"Quit"——用户单击按钮退出SDK

"Retry"——用户单击并再次尝试扫描证件;SDK不退出

证件不完整

The ID is not complete

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

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

"Quit"——用户单击按钮退出SDK

"Retry"——用户单击并再次尝试扫描证件;SDK不退出

证件错误

No ID detected

Please make sure you are using the required type of ID.

采集的证件不是请求的证件类型

"Quit"——用户单击按钮退出SDK

"Retry"——用户单击并再次尝试扫描证件;SDK不退出

未知证件

No ID detected

Please make sure you are using the required type of ID.

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

"Quit"——用户单击按钮退出SDK

"Retry"——用户单击并再次尝试扫描证件;SDK不退出

未检测到证件

No ID detected

Please make sure you are using the required type of ID.

没有采集到任何证件

"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