Error handling

If an error occurs when you call an API, an error response will be returned, where the result field indicates the error code ( result.resultCode ) and error message ( result.resultMessage ). You can troubleshoot specific issues based on the error codes section below. If the error persists, you may also contact ZOLOZ's technical support team for assistance.

Error codes

ZOLOZ returns two kinds of error codes:

  • Common error codes that applies to all APIs – which indicate the invocation status of an API request
  • API-specific error codes that applies only to a specific API – which indicate the detailed processing result of the specific API

Common error codes

The following table lists information about the common error codes. If you do not find an error code here, please see the API-specific error codes section instead.

Incomplete integration may cause error result, for correct integrate process,please refer:Get API credentials ready

resultCode

resultStatus

resultMessage

SUCCESS

S

The request has succeeded.

PARAM_MISSING

F

Bad request. The parameter is missing.

PARAM_ILLEGAL

F

Bad request. The parameter is illegal.

MSG_PARSE_ERROR

F

Bad request. The message format is invalid.

SIGNATURE_INVALID

F

Unauthorized. The signature is invalid.

KEY_NOT_FOUND

F

Key not found.

Unauthorized. The ZOLOZ server is unable to find the key.

MERCHANT_NOT_FOUND

F

Merchant not found.

The ZOLOZ server is unable to find the merchant.

OAUTH_FAIL

F

Unauthorized. The OAuth 2.0 authorization has failed.

OAUTH_RESOURCE_CODE_FAIL

F

Unauthorized. The resource code is blank.

ACCESS_DENIED

F

Unauthorized. No access to the API.

NO_INTERFACE_DEF

F

The requested API is not defined.

REQUEST_TRAFFIC_EXCEED_LIMIT

F

The request traffic has exceeded the limit.

PRODUCT_QUOTA_LIMIT

F

Product usage has exceeded the limit.

SYSTEM_ERROR

U

A system error has occurred.

PROCESS_TIMEOUT

F

The processing of the API request has timed out.

API-specific error codes

For error codes that apply to a specific API, see the Result section in each API specification.

SDK-specific error codes

  • SDK Callback results For client-side SDK information, you will only need to focus on the SDK callback results. 
    The SDK callback results are: complete and interrupt
    • If the SDK callback result is complete, call the server-side API e.g. checkresult to retrieve the status and result;
    • If the SDK callback result is interrupt, a pop-up window alert will be displayed to the client (e.g. network error, timeout, etc.). The SDK will also return a code (i.e. four digits starting with Z) and the user will have the option to choose "Quit" or "Got it", or other actions to close the SDK. You can then proceed with the subsequent processes according to business requirements, such as guiding the user to retry, or waiting for a human review.
  • Handling SDK integration
    • During developer integration, if the SDK reports an error, you can troubleshoot the error by referring to the table above. For easy reference, the table only contains the common error codes often encountered during integration.
    • If the SDK has been integrated properly and the entire process runs smoothly, the return code can be ignored. The code will only be used for further troubleshooting by the ZOLOZ technical support team when it comes to customer feedback.

SDK Callback Results

You will need to pay attention to the SDK callback results.
There are two possible SDK outcomes:
complete and interrupt.

The following callback content corresponds to the Android and iOS SDKs respectively: 

Android

iOS

SDK Complete

After the SDK collection and the client-side process is completed, you will need to call the server-side checkresult interface to view the business status and results. 

SDK Interrupt

The SDK collection is interrupted, and the SDK is closed; obtaining this callback result indicates that the operation has ended. 

In the case of an interruption, the server-side status will be divided into two cases: 

  • If the user cancels (by clicking "Quit" or "Got it"), the server will be notified and the server status will change to cancel. 
  • In the case of a background termination or system exception, the SDK will not be able to perceive it or notify the server. This means that the server status will still be processing, and the SDK callback information will not conflict with the server side interface status. 

If interrupted, a corresponding pop-up window will be displayed to the client (e.g. network error, timeout, etc) and the user will have to choose the options "Quit" or "Got it", or other actions to close the transaction. Therefore, the test method can be adjusted according to the pop-ups.

See Pop-up Window Descriptions below for each pop-up description and explanation. 

Client Error Pop-up Windows

These pop-ups are visible to online C-side users, and you will only need to fill in the corresponding copy; there is no need to process the business logic for each pop-up.

Error Pop-up Window Customization

The UI Configuration platform allows you to view all pop-up windows and customize the title, copy and button content for each pop-up. 

Pop-up Window Descriptions 

Pop-up

Default Header

Default Copy 

Reason

Button 

System Error

System error 

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

"Got it" – the user clicks the button and exits the SDK

Network Error 

Internet connection failure 

Please check your internet connection and try again. 

Network connection failure

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries connecting to the network again; the SDK does not exit

Access Camera Failure

No camera permission

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

Camera permissions are not authorized

"Quit"  – the user clicks the button and exits the SDK

"Go to settings" – the user clicks to authorize camera permissions; the SDK does not exit 

Retry Limit Reached

Too many attempts

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

The user has made multiple document/face scans and the number of retries has exceeded the limit set.

"Quit"  – the user clicks the button and exits the SDK

User Quits ID Recognition

Are you sure you want to quit? 

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

The user clicked to exit the document scanning interface.

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

Expired Document

ID expired

Make sure your ID is not expired.

Expired documents

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

No Face Detected in the Document

The portrait is incomplete

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

There is no face detected on the document

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

Document is Overexposed

ID over exposure

Please adjust the lighting to avoid over exposure.

The document is overexposed

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

Document is Not Clear

ID not clear

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

The blurry document does not pass the quality test

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

Document is Not Complete

ID not complete

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

The document is not captured completely and does not pass quality testing

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

Wrong Document

Incorrect ID type detected

Make sure you are using the required type of ID.

The document captured is not the type of document requested

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

Unknown Document

Incorrect ID type detected

Make sure you are using the required type of ID.

Unknown document type. The document captured is not the required document type.

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

No Document Detected

No ID detected

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

No document captured

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries scanning the document again; the SDK does not exit

User Quits Face Recognition

Are you sure you want to quit?

Please face the camera directly for easy capturing.

The user tapped out of the face capture interface

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries face scanning again; the SDK does not exit

Face Recognition Failure

Face verification failed

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

The face capture has failed. The face comparison between the live capture and document portrait does not match enough to meet the passing threshold. The user will have to re-capture their face again. This error seldom occurs.

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries face scanning again; the SDK does not exit

Face Recognition Timeout

Operation Timeout

Please face the camera directly for easy capturing.

Face scanning has timed out. The face was not detected within the set-time frame to meet face capture requirements.

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries face scanning again; the SDK does not exit

Face Recognition Interruption

Face verification interruption

Please face the camera directly for easy capturing.

The face capture process may have been interrupted due to app swithing in the background, etc. Users can only choose to retry/quit when they return to the app again.

"Quit"  – the user clicks the button and exits the SDK

"Retry" – the user clicks and tries face scanning again; the SDK does not exit

Device is not supported

Face verification is not supported on this device.

The device is at risk of being blocked by a policy blacklist, or the device does not support cameras and thus cannot scan or capture. This error seldom occurs.

"Got it" – the user clicks and exits the SDK

Camera Init Fail

Face verification is not supported on this device.

Due to a hardware problem, the device does not support face scanning, so bringing up the camera leads to failure and the user is unable to proceed. This error seldom occurs.

"Got it" – the user clicks and exits the SDK

Doc Camera Init Fail

Document capture is not supported on this device.

Due to a hardware problem, the device does not support document scanning, so bringing up the camera leads to failure and the user is unable to proceed. This error seldom occurs.

"Got it" – the user clicks and exits the SDK

retCode

Z10XX

retCode

Description

Z1000

Algorithm model error or system error (Android)

Parameter parsing exception (bioType error) issued by the server (iOS)

Z1001

Client algorithm initialization failed

Z1002

Unable to start camera

Z1003

Unsupported hardware (CPU)

Z1004

Operating system version is too low

Z1005

One-time face scan timeout

Z1006

Number of retries exceeds the limit

Z1008

User actively exited from face scan

Z1009

Exit when switching background Apps

Z1010

Internal reflection is abnormal or the corresponding page cannot be found (Android)

zimid is null (iOS)

Z1012

Network Error

Z1013

Liveness detection failed

Z1016

User clicked the Exit button in the retry popup box

Z1018

No front camera

Z1019

No camera usage permission

Z1020

Fail to open the camera

Z1021

Camera has no image stream

Z1022

Verification is interrupted due to internal error

Z1024

Last verification is being processed

Z2XXX

retCode

Description

Z2000

System Error

Z2001

Android:

  • No front camera
  • Camera initialization failed
  • No camera usage permission

iOS:

  • No camera usage permission
  • Client algorithm load failed

Z2002

User actively exited

Z2003

Network connection exception

Z2006

The number of retries exceeds the limit

Z2007

User choosed to exit due to failure during the anti-spoofing detection

Z2341

No document detected

Z50XX

retCode

Description

Z5001

Request protocol error

Z70XX

retCode

Description

Z7001

Not connected to the internet

Z7002

User wants to quit

Z7003

eKYC invokes the callback onComplete, and the result is Success (only for Android)

Z7005

eKYC invokes the callback onComplete, and the result is Pending (only for Android)

Z7010

Incorrect return value of clientCfg

Z7011

Context is null (Android) 

Viewcontroller is null (iOS)

Z7012

clientCfg is null

Z7013

FLOW_TYPE is null

Z7014

No config file

Z7015

Read file failure

Z7016

No web service config file (only for Android)

Z7017

Reflection fail (only for Android)

Z7018

zimid is null

Z7019

bizDataKey's value is null

Z7020

Url for the Web Task in the zlzconfig is null

Z7021

Current task is not webTask

Z7022

rpc exception except network problem

Z7023

H5 key parameters check failure

Z7024

Specific analysis depending on the issue needed

Z7025

zimid key is null

Z7026

Url pattern is null

Z7027

Cannot find url pattern in config

Z7028

Incorrect task index

Z7029

Incorrect task type

Z7030

Incorrect server task name

Z7031

Incorrect config format

Z7032

zimInitResp in the nativeTask is null

Z7033

webTask Result Processing Error

Z7035

Document or face collection succeeded

Z7075

Camera initialization failed

Z7076

Fail to open the camera

Z7077

Algorithm initialization failed due to the model file error that blocks user operation

Z7078

The server returned an unrecognized return code to the client

Z90XX

retCode

Description

Z9003

ZOLOZ CONNECT recognition success

Z9004

ZOLOZ CONNECT recognition failure