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.
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:
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 |