Reference for ZOLOZ API result codes, SDK callback results, and client-side error pop-ups.
When an API call fails, the result field contains the error code (result.resultCode) and error message (result.resultMessage). Troubleshoot using the error codes below. If the error persists, contact ZOLOZ technical support.
Error codes
ZOLOZ returns two kinds of error codes:
-
Common error codes that apply to all APIs – indicate the invocation status of an API request
-
API-specific error codes that apply only to a specific API – indicate the detailed processing result
Common result codes
The following table lists common result codes. If your code is not listed here, check the API-specific result codes.
Incomplete integration may cause errors. Ensure you have completed the setup in 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 result codes
Each API specification contains a Result section with API-specific codes.
SDK-specific error codes
-
SDK Callback results For client-side SDK integration, 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 checkresult API to retrieve the status and result.
-
If the SDK callback result is interrupt, the SDK displays a pop-up (e.g. network error, timeout) and returns a four-digit code starting with Z. The user can choose "Quit" or "Got it" to close the SDK. Handle the interruption based on your business requirements, such as guiding the user to retry or waiting for manual review.
-
Handling SDK integration
-
During integration, troubleshoot SDK errors using the table above, which lists common error codes encountered during integration.
-
After successful integration, you can ignore the return code. It is only used by ZOLOZ technical support for troubleshooting customer-reported issues.
SDK Callback Results
The SDK returns two possible callback outcomes: complete and interrupt.
Callback references for Android and iOS:
Android
iOS
SDK Complete
After the SDK completes client-side collection, call the server-side checkresult API to get the business status and results.
SDK Interrupt
The SDK collection is interrupted and the SDK closes. This callback indicates the operation has ended.
When interrupted, the server-side status depends on the cause:
-
If the user cancels (clicks "Quit" or "Got it"), the server is notified and the status changes to cancel.
-
For background termination or system exceptions, the SDK cannot notify the server. The server status remains processing, and the SDK callback does not conflict with the server-side status.
On interruption, the SDK displays a pop-up (e.g. network error, timeout) and the user must choose "Quit", "Got it", or another action to close the transaction. Adjust your test methods based on the pop-up type.
The Pop-up Window Descriptions table below lists each pop-up and its trigger.
Client Error Pop-up Windows
These pop-ups are displayed to end users. You only need to customize the copy; no business logic processing is required for each pop-up.
Error Pop-up Window Customization
The UI Configuration platform lets you view and customize the title, copy, and button text 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
Do not use retCode for business logic. retCode is only for troubleshooting and data analysis when a client-side exception occurs.
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:
iOS:
|
|
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 |