Financial-grade Real Person Authentication server-side API error codes-ID Verification(ID Verification)-阿里云帮助中心

API: InitFaceVerify

Code and message

Code	Message	Description
200	success	The request was successful.
400	Parameter cannot be empty	A required parameter is missing.
401	Invalid parameter	The parameter is invalid. The provided name and ID number must comply with national standards.
402	Application configuration does not exist	The application configuration does not exist.
404	Authentication scenario configuration does not exist	The authentication scenario is not configured. Go to the console to create an authentication scenario.
410	Service not activated	The OSS service is not activated, or read/write access to OSS is not authorized. Log on to the console to grant the necessary permissions. For more information, see Activate and Authorize OSS Storage.
411	No RAM permission	The RAM user does not have the required permissions. You must grant the AliyunAntCloudAuthFullAccess permission to the RAM user.
412	Overdue payment	Your Financial-grade Real Person Authentication or OSS account has an overdue payment. Top up your account and try again.
414	Device type not supported	The current mobile device does not support face verification. Switch to another device and try again.
415	SDK version not supported	The current SDK version does not support face verification. Upgrade the SDK and try again.
416	OS version not supported	The current operating system version does not support face verification. Upgrade your OS or switch to another device.
417	Unable to use face verification service	The authoritative data source for identity comparison is unavailable. If the provided information is correct, manual review is recommended.
500	System error	An internal system error occurred. Please submit a ticket for assistance.

APIs: DescribeFaceVerify and DescribeFaceGuardRisk

Code and message

Code	Message	Description
200	success	The request was successful.
400	Parameter cannot be empty	A required parameter is missing.
401	Invalid parameter	The parameter is invalid. The provided name and ID number must comply with national standards.
402	Application configuration does not exist	The application configuration does not exist.
403	Authentication not completed	This can occur if you submit duplicate requests or call the authentication interface too frequently.
404	Authentication scenario configuration does not exist	The authentication scenario is not configured. Go to the console to create an authentication scenario.
406	Invalid CertifyId	The provided CertifyId is invalid.
410	Service not activated	The OSS service is not activated, or read/write access to OSS is not authorized. Log on to the console to grant the necessary permissions. For more information, see Activate and Authorize OSS Storage.
411	No RAM permission	The RAM user does not have the required permissions. You must grant the AliyunAntCloudAuthFullAccess permission to the RAM user.
412	Overdue payment	Your Financial-grade Real Person Authentication or OSS account has an overdue payment. Top up your account and try again.
414	Device type not supported	The current mobile device does not support face verification. Switch to another device and try again.
415	SDK version not supported	The current SDK version does not support face verification. Upgrade the SDK and try again.
416	OS version not supported	The current operating system version does not support face verification. Upgrade your OS or switch to another device.
417	Unable to use face verification service	The authoritative data source for identity comparison is unavailable. If the provided information is correct, manual review is recommended.
424	Identity verification record does not exist	The authentication for the current CertifyId is not yet complete. We recommend calling this query interface only after the client receives a callback with a status of 1000 or 2006. Note The query interface returns this error code if the CertifyId has not been used for authentication, the user abandoned the process, or the authentication is still in progress.
427	Restricted by business policy	Authentication failed due to an internal risk control policy.
500	System error	An internal system error occurred. Please submit a ticket for assistance.

ResultObject.SubCode error codes

Subcode	Message	Resolution
200	Authentication passed	The call was successful.
201	Name and ID number do not match	The user's information may be incorrect or fraudulent. Advise the user to verify their information and try again.
202	Identity information not found	This may occur due to special circumstances like a household registration change. We recommend providing an option for manual review.
203	Photo not found or unavailable	This may be caused by an issue with the authoritative data source. We recommend providing an option for manual review.
204	Face comparison mismatch	The person in the video may not be the same person as in the ID photo, or the quality of the liveness photo is low. We recommend handling this based on your business requirements. If they are the same person, they can try again. Note If the same user fails authentication multiple times, advise them to try again in a well-lit environment and ensure their face is not obstructed. Alternatively, you can adjust the threshold based on the comparison score returned by the query interface to better match your business needs.
205	Liveness detection risk detected	A potential attack was detected. We recommend a layered approach with manual review. If the user is genuine, they can try again.
206	Restricted by business policy	To ensure security, the service performs security checks on the device, identity, face, and environment. If a potential risk is detected, the authentication fails. Common risks include: The device exhibits high-risk characteristics, such as camera hijacking, root access, code injection, or running in an emulator. The device or identity has been used for frequent authentication attempts within a short period. You can troubleshoot this issue as follows: Advise the user to uninstall any multi-instance, cloning, or virtual environment applications or plugins from their device, restore the device to its original security state, and then try again. If this is for internal testing or you have already confirmed the user is legitimate offline, you can log on to the Financial-grade Real Person Authentication console and add the user to the whitelist on the General Settings > Whitelist Settings page.
207	Face does not match ID photo	This sub-code is returned only when using the ID_PLUS solution. This may indicate a person-ID mismatch or a low-quality face photo. We recommend a layered approach based on your business needs. If they are the same person, they can try again.
209	Authoritative data source error	An error with the authoritative data source may have occurred, preventing a comparison.
220	Intention check failed	The user did not express their intent for the specific business action, or expressed it unclearly. If the expression was unclear, they can try again.
221	Voiceprint mismatch	The speaker may not be the same person, or the audio quality may be low. We recommend a layered approach based on your business needs. If they are the same person, they can try again.
222	General authentication failed	Failed to retrieve the ID document information.

FAQ

Troubleshoot verification failures or parameter errors

Follow these steps to troubleshoot the issue:

Obtain key troubleshooting information
The complete response from the API call is the primary source for troubleshooting. Regardless of whether server-side logs are available, always check the RequestId, Code, Message, and SubCode fields in the response body. The RequestId is a unique identifier for each API call and is crucial for locating the issue. We recommend that you save it.
Identify the cause based on the error code
Use the Code or SubCode and the corresponding Message from the response body to identify the cause of the error.
Do not rely solely on local logs
Always use the complete API response, especially the RequestId and error codes, as the primary source for investigating errors. Avoid relying solely on local logs.