The CAPTCHA initialization API fetches CAPTCHA resources using a request that includes your user tag (prefix). Requests are sent to xxxxx.captcha-open.aliyuncs.com, where xxxxx is your user tag. To get your user tag, see Activate Captcha Service.
A successful initialization response looks like this:
API error codes
When initialization fails, the API returns one of the following error codes:
| Error code | Type | Description and fix |
|---|---|---|
IllegalUserTag | Configuration | The user tag (prefix) parameter is invalid. See Activate Captcha Service to confirm the value is passed correctly. Important This error applies only to Web and H5 client integration and App client integration — not WeChat mini program integration. |
IllegalCertifyId | Configuration | The certifyId (UserCertifyId) format is invalid. The required format is: [user tag (prefix)]_[10-digit string of uppercase letters, lowercase letters, and digits]. For code samples, see UserCertifyId parameter code samples. |
IllegalScene | Configuration | The scene ID (SceneId) parameter is invalid. Confirm the SceneId value is correct and that the scene was created under the account associated with the user tag (prefix). |
Forbidden.AccountAccessDenied | Account | The account has an overdue payment. Check that the account status is Normal. |
Throttling | Rate limiting | The number of queries per second (QPS) exceeds the product limit. If you require a higher QPS, contact your account manager in advance for confirmation. |
ThrottlingByStrategy | Rate limiting | The initialization request rate limit was triggered. This is a security mechanism that blocks attempts to traverse the CAPTCHA question library by sending requests at a high frequency. |
Parameter validation errors
If a parameter value is invalid, initialization fails with a field-level error. The following table lists each affected field and how to fix it:
| Field | Description and fix |
|---|---|
| General type verification | The parameter type is invalid. See Parameter description and pass a value of the correct type. |
language | The language parameter value is invalid. See Languages supported by Captcha 2.0 for valid values. |
region | The region parameter value is invalid. See region parameter description for requirements. |
mode | The mode parameter value is invalid. Supported values are popup and embed. See mode parameter description for details. |
element/button | The element or button element does not exist on the page, or the parameter value does not match the ID selector of the element on the page. Confirm that the element exists and that the parameter matches its ID selector. |
Field | Error message |
General type validation | An input parameter has an invalid data type. See the Parameter descriptions for the correct data types. |
language | The |
region | The |
mode | The |
element/button | The |