1. API Description
Domain name for API request: captcha.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 | It must be 9 here. |
| 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 | 1 OK: Verification passed7 captcha no match: The passed in Randstr is invalid. Make sure it is the same as the Randstr returned from the frontend.8 ticket expired: The Ticket has expired. A ticket is valid for five minutes. Please generate a new Ticket and Randstr.9 ticket reused: The specified Ticket has been used. Please generate a new Ticket and Randstr.15 decrypt fail: The specified Ticket is invalid. Make sure it's the same as the Ticket returned from the frontend. 16 appid-ticket mismatch: The specified CaptchaAppId is invalid. Make sure it's the same as the CaptchaAppId returned from the frontend. You can obtain it from the CAPTCHA console in Verification management > Basic configuration.21 diff. Ticket verification error. Possible reasons: 1) If the ticket contains the terror prefix, it's usually the case that a disaster recovery ticket is generated due to the network connection problems of the user. You can choose to ignore it or verify again. 2) If the ticket does not include the terror prefix, Captcha detects security risk on this request . You can choose to block it or not.100 appid-secretkey-ticket mismatch: Parameter error. 1) Make sure CaptchaAppId and AppSecretKey are correct. CaptchaAppId and AppSecretKey in the CAPTACHA console under Verification management > Basic configuration. 2) Make sure the passed-in Ticket is generated by using the passed-in CaptchaAppId. |
| CaptchaMsg | String | Status description and verification error message Note: This field may return null, indicating that no valid value was found. |
| EvilLevel | Integer | This parameter returns the result of imperceptible verification. This parameter is not available for Tencent Cloud International yet.0: The request is trusted.100: The request is malicious.Note: This field may return null, indicating that no valid value was found. |
| GetCaptchaTime | Integer | The timestamp when the frontend obtains the CAPTCHA. Note: This field may return null, indicating that no valid value was found. |
| 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 |
| 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 response examples
This example shows you how to verify the ticket.
Input Example
POST / HTTP/1.1
Host: captcha.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,
"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.
- Tencent Cloud SDK 3.0 for Python
- Tencent Cloud SDK 3.0 for Java
- Tencent Cloud SDK 3.0 for PHP
- Tencent Cloud SDK 3.0 for Go
- Tencent Cloud SDK 3.0 for Node.js
- Tencent Cloud SDK 3.0 for .NET
- Tencent Cloud SDK 3.0 for C++
Command Line Interface
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 |
Yes
No
Was this page helpful?