tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Documentation

DescribeCaptchaResult

Last updated: 2024-10-30 15:12:22

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

    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
    Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
    Privacy PolicyLegalCookie Policy