DescribeCaptchaResult

下载PDF

最后更新时间：2025-10-30 21:30:21

DescribeCaptchaResult

最后更新时间： 2025-10-30 21:30:21

下载PDF

1. API Description

Domain name for API request: captcha.intl.tencentcloudapi.com.

This API is used to query the result of CAPTCHA ticket verification (web and app).

A maximum of 1000 requests can be initiated per second for this API.

We recommend you to use API Explorer

Try it

API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name	Required	Type	Description
Action	Yes	String	Common Params. The value used for this API: DescribeCaptchaResult.
Version	Yes	String	Common Params. The value used for this API: 2019-07-22.
Region	No	String	Common Params. This parameter is not required for this API.
CaptchaType	Yes	Integer	Fill with fixed value: 9.
Ticket	Yes	String	The user verification ticket returned by the frontend callback function
UserIp	Yes	String	The user public IP obtained from the customer backend server
Randstr	Yes	String	A random string returned by the frontend callback function
CaptchaAppId	Yes	Integer	CAPTCHA's app ID. Log in to the Captcha console and you can view the CaptchaAppId in the "Key" column of the CAPTCHA list.
AppSecretKey	Yes	String	CAPTCHA's app key. Log in to the Captcha console and you can view the AppSecretKey in the "Key" column of the CAPTCHA list. AppSecretKey is the key for CAPTCHA ticket verification performed by the server. Please keep it confidential and do not disclose it to any third parties.
BusinessId	No	Integer	Reserved field.
SceneId	No	Integer	Reserved field.
MacAddress	No	String	MAC address or unique identifier of a device
Imei	No	String	Mobile equipment identity number
NeedGetCaptchaTime	No	Integer	Indicates whether to return the time when the frontend obtains the CAPTCHA. Valid values: 1 (return the time) and others.

3. Output Parameters

Parameter Name	Type	Description
CaptchaCode	Integer	OK indicates verification passed. 7 captcha no match. the passed in Randstr is invalid. please check if the Randstr is consistent with the Randstr returned by the frontend. The passed-in ticket has expired (the valid period of the ticket is 5 minutes). generate the ticket and Randstr again for validation. The passed-in ticket is reused. generate the ticket and Randstr again for verification. 15 decrypt fail. the passed-in Ticket is invalid. please check if the Ticket is consistent with the Ticket returned by the frontend. 16 appid-ticket mismatch. the passed in CaptchaAppId is incorrect. please check if the CaptchaAppId is consistent with the CaptchaAppId passed in by the frontend, and ensure that the CaptchaAppId is obtained from the verification code console [verification management] -> [basic configuration]. 21 diff invoice verification exception. possible reasons: (1) if the Ticket contains the trerror prefix, generally because the user has a poor network connection, resulting in the frontend's automatic disaster recovery and generation of a disaster recovery Ticket. the business side may skip or post-process as needed. (2) if the Ticket does not include the trerror prefix, it is because the security risk of the request was detected by the CAPTCHA-intl risk control system. the business side may intercept as needed. 100 appid-secretkey-ticket mismatch. parameter validation error. (1) please check whether the CaptchaAppId and AppSecretKey are correct. the CaptchaAppId and AppSecretKey need to be obtained from verification code console > verification management > basic configuration. (2) please check whether the passed-in ticket is generated by the passed-in CaptchaAppId.
CaptchaMsg	String	Status description and verification error message.
EvilLevel	Integer	In invisible verification mode, this parameter returns the verification result. EvilLevel=0 indicates that the request is not malicious. The parameter EvilLevel = 100 indicates that the request is malicious.
GetCaptchaTime	Integer	Frontend retrieval time of the captcha-intl, timestamp format.
EvilBitmap	Integer	Blocking type Note: This field may return null, indicating that no valid values can be obtained.
SubmitCaptchaTime	Integer	The time when the CAPTCHA is submitted.
DeviceRiskCategory	String	Device risk category. Note: This field may return null, indicating that no valid values can be obtained.
Score	Integer	CAPTCHA-Intl score. Note:The score ranges from 0 to 100 (e.g., 20, 70, 90). A higher score indicates a greater probability that the interaction was initiated by a bot or represents a bot attack. A lower score indicates a greater probability that the interaction was performed by a real human user.
RequestId	String	The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Request and Return Example

Invoice verification

Input Example

POST / HTTP/1.1
Host: captcha.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeCaptchaResult
<Common request parameters>

{
    "CaptchaAppId": 199999164,
    "CaptchaType": 9,
    "NeedGetCaptchaTime": 1,
    "Randstr": "@Vki",
    "UserIp": "127.0.0.1",
    "Ticket": "tr03XaCUZPAlPdIMqv17yvcfdXCzkqvLE09AbCA4ghlWfD8hkySfbU2TZVCyoOCjNI84pAYEMopKv7Uh8XwQDSE9DC0xJpXVC7kmlPENlbFINs_N937qkoEmU6Pl8e-9EkFQzvrrwsZOTKQ*",
    "AppSecretKey": "E4kwK9AcXQMHkktiItyMEyQPn"
}

Output Example

{
    "Response": {
        "CaptchaCode": 0,
        "CaptchaMsg": "not valid",
        "EvilLevel": 0,
        "GetCaptchaTime": 1729583235,
        "SubmitCaptchaTime": 1729583239,
        "EvilBitmap": 0,
        "DeviceRiskCategory": "501",
        "Score": 60,
        "RequestId": "7c370964-7deb-4008-8b29-47e87e60c1e0"
    },
    "retcode": 0,
    "retmsg": "success"
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

Tencent Cloud CLI 3.0

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code	Description
InternalError	Internal error.
MissingParameter	Missing parameter.
UnauthorizedOperation.ErrAuth	Authentication failed.
UnauthorizedOperation.Unauthorized	Operation not authorized/No valid package/The account is overdue

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

是

否

文档反馈

tencent cloud