Every Fraud Detection API request requires a set of common parameters in addition to the operation-specific service parameters. This topic describes those common parameters and the response fields returned for every call.
Common request parameters
The parameters below are required for all API operations.
The signature string. For more information about how to calculate the signature, see Section 2.0 of Signature Mechanism: SDK-based Calls.
| Parameter | Type | Required | Description |
|---|---|---|---|
| Format | String | Yes | Response format. Valid values: JSON (default), XML. |
| Version | String | Yes | API version in YYYY-MM-DD format. Current version: 2019-05-21. |
| AccessKeyId | String | Yes | Your AccessKey ID from the Alibaba Cloud console. |
| Signature | String | Yes | The request signature. See Make API requests for the signing algorithm (section 2.0). |
| SignatureMethod | String | Yes | Signature algorithm. Only HMAC-SHA1 is supported. |
| Timestamp | String | Yes | Request timestamp in UTC, formatted as yyyy-MM-ddTHH:mm:ssZ (ISO 8601). Example: 2019-08-22T01:44:35Z represents 09:44:35 on August 22, 2019 (UTC+8). |
| SignatureVersion | String | Yes | Signature algorithm version. The value is 1.0. |
| SignatureNonce | String | Yes | A unique random string for each request, used to prevent replay attacks. |
| Action | String | Yes | The API action to invoke. Valid values: ExecuteRequestSG (Singapore), ExecuteRequestML (Malaysia).Valid values are ExecuteRequestSG (Singapore) and ExecuteRequestML (Malaysia). |
| Service | String | Yes | The detection service to use. Valid values: device_risk (Device Risk Detection Service), device_risk_pro (Device Risk Detection - Advanced Service). |
| ServiceParameters | String | Yes | Service-specific event parameters as a JSON string. For example: {"accountId":10123****}. See Event parameters for device risk detection for the full parameter reference. |
Sample request
The following request calls the Device Risk Detection - Advanced Service:
https://saf.{region}.aliyuncs.com/
?Format=JSON
&Version=2020-07-06
&Signature=vpEEL0zFHfxXYzSFV0n7%2FZiFL9o%3D
&SignatureMethod=Hmac-SHA1
&SignatureNonce=15215528852396
&SignatureVersion=1.0
&Action=ExecuteRequest
&AccessKeyId=123****saf
&Timestamp=2018-06-01T12:00:00Z
&Service=device_risk_pro
&ServiceParameters={"deviceToken":1012****}The following code provides a sample request for the Device Risk Detection - Advanced Service:
{
// service: device_risk_pro
"RequestId": "52E3208D-E7BF-32F0-9913-2A168894D2D9",
"Message": "OK",
"Data": {
"extend": "0f533f6056f50664b48f2b3866220f0f", // Unique device ID
"tags": "is_rooted" // Reason code
},
"Code": 200 // The request is successful.
} Common response parameters
Every API response includes a RequestId, regardless of whether the call succeeds. The Data object contains service-specific fields — score, tags, and extend — whose content varies by service.
The following is a sample JSON response from the Device Risk Detection - Advanced Service:
{
"RequestId": "52E3208D-E7BF-32F0-9913-2A168894D2D9",
"Message": "OK",
"Data": {
"extend": "0f533f6056f50664b48f2b3866220f0f",
"tags": "is_rooted"
},
"Code": 200
}| Field | Description |
|---|---|
RequestId | Unique identifier for the request. Include this value when contacting support. |
Message | Status message. OK indicates a successful call. |
Code | HTTP status code. See Error codes for the full list. |
Data.extend | Unique device ID assigned by the service. |
Data.tags | Reason code describing the detection result. |
Sample responses in this topic are formatted for readability. Actual responses are not formatted with line breaks or indentation.
The following code provides a sample response in JSON format for the Device Risk Detection - Advanced Service:
Error codes
| Code | Description | Action |
|---|---|---|
| 200 | The request succeeded. | — |
| 400 | The value of ServiceParameters is invalid. | Check the parameter format and required fields against the event parameter reference. |
| 402 | The request rate exceeds your purchased QPS (queries per second) limit. Throttling is active. | Reduce request frequency or upgrade your service plan. Use exponential backoff when retrying. |
| 403 | The request lacks the required permissions. The service is not activated or has expired. | Verify that Fraud Detection is activated in the Alibaba Cloud console and that the AccessKey ID has the required permissions. |
| 404 | The value of the Service parameter is invalid. | Use a valid value: device_risk or device_risk_pro. |
| 500 | An internal server error occurred. | Retry the request. If the error persists, contact Alibaba Cloud support with the RequestId. |