AECC 能管系统 SDK 接入指南

安全鉴权与加密流程

所有开放接口调用均需通过严格的签名验证，确保通信安全与数据完整性。

1. 获取接入凭证

联系 AECC 官方获取专属接入凭证：

• companyCode：企业唯一识别码（用于请求头身份标识）
• key：接口签名密钥（仅用于本地签名生成，严禁在网络中明文传输）

凭证安全管理建议：

• 密钥应存储在服务器端配置文件或环境变量中，禁止硬编码在客户端代码
• 定期（建议每季度）审查密钥使用情况，发现异常立即联系官方重置
• 不同环境（测试/生产）应使用不同的凭证，避免相互影响
• 限制密钥访问权限，仅核心开发人员知晓，离职时需更换密钥

2. 构造待签名字符串

按以下固定规则拼接签名原文，顺序错误将导致验签失败：

• 业务参数排序：将所有业务请求参数（不包含 time 和 sign）的参数名，按 Unicode 编码升序 排列，拼接为 key=value&key=value 格式。
• 追加时间与密钥：在排序后的字符串末尾，固定追加 time={UTC+0秒级时间戳}&key={分配的密钥}。
• 完整示例：datalogSn=SXDID888888&deviceSn=SXDID888888XXXXXX&time=1723720871&key=2a1891544dbcf8e8b45b36d03187485a

详细构造步骤：

步骤 2.1：提取业务参数 从请求体中提取所有业务参数，排除 time 和 sign 字段：

{
  "energyMode": "2",
  "aiMode": "0", 
  "customTimes": "00:00,12:00,1000&13:00,15:00,-2000",
  "batRatedCapacity": "1",
  "batRatedChargingPower": "1000",
  "dataTime": "2025-06-26",
  "priceCompany": "Germany"
}
步骤 2.2：参数名排序
按 Unicode 编码升序排列参数名：
aiMode, batRatedCapacity, batRatedChargingPower, customTimes, dataTime, energyMode, priceCompany

步骤 2.3：拼接参数字符串 按排序结果拼接为 key=value 格式，用 & 连接：

aiMode=0&batRatedCapacity=1&batRatedChargingPower=1000&customTimes=00:00,12:00,1000&13:00,15:00,-2000&dataTime=2025-06-26&energyMode=2&priceCompany=Germany

步骤 2.4：追加时间戳与密钥 在字符串末尾追加 time 和 key：

aiMode=0&batRatedCapacity=1&batRatedChargingPower=1000&customTimes=00:00,12:00,1000&13:00,15:00,-2000&dataTime=2025-06-26&energyMode=2&priceCompany=Germany&time=1732756652&key=2a1891544dbcf8e8b45b36d03187485a

注意事项：

• 参数值为空字符串时，仍需参与签名（如 status=&time=...&key=...）
• 参数值包含特殊字符无需 URL 编码，直接原值拼接
• 时间戳必须使用 UTC+0 时区的秒级时间戳，与服务端保持一致
• 密钥值必须使用官方分配的原始密钥，不得进行任何转换

3. 生成签名值

使用标准 MD5 算法对拼接完成的待签名字符串进行哈希运算，输出结果必须转换为 全小写 字符串，作为 sign 参数值。

多语言签名示例：

Java 示例：

import java.security.MessageDigest;
import java.util.TreeMap;

public class SignGenerator {
    
    public static String generateSign(TreeMap<String, String> params, String key) {
        try {
            // 参数已排序（TreeMap自动排序）
            StringBuilder sb = new StringBuilder();
            
            // 拼接业务参数
            for (String paramKey : params.keySet()) {
                if (!paramKey.equals("sign")) {  // 排除sign字段
                    sb.append(paramKey).append("=").append(params.get(paramKey)).append("&");
                }
            }
            
            // 追加time和key
            sb.append("time=").append(params.get("time")).append("&key=").append(key);
            
            // MD5加密并转小写
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(sb.toString().getBytes("UTF-8"));
            
            StringBuilder hexString = new StringBuilder();
            for (byte b : digest) {
                String hex = Integer.toHexString(0xff & b);
                if (hex.length() == 1) hexString.append('0');
                hexString.append(hex);
            }
            
            return hexString.toString().toLowerCase();
        } catch (Exception e) {
            throw new RuntimeException("签名生成失败", e);
        }
    }
}
Python 示例：
import hashlib
from urllib.parse import urlencode

def generate_sign(params, key):
    """
    生成API签名
    :param params: 业务参数字典（包含time）
    :param key: 分配的密钥
    :return: MD5签名字符串（小写）
    """
    # 排除sign字段，按key排序
    sorted_params = sorted([(k, v) for k, v in params.items() if k != 'sign'])
    
    # 拼接参数
    param_str = '&'.join([f"{k}={v}" for k, v in sorted_params])
    
    # 追加time和key
    sign_str = f"{param_str}&time={params['time']}&key={key}"
    
    # MD5加密并转小写
    return hashlib.md5(sign_str.encode('utf-8')).hexdigest().lower()

# 使用示例
params = {
    'energyMode': '2',
    'aiMode': '0',
    'customTimes': '00:00,12:00,1000&13:00,15:00,-2000',
    'batRatedCapacity': '1',
    'batRatedChargingPower': '1000',
    'dataTime': '2025-06-26',
    'priceCompany': 'Germany',
    'time': '1732756652'
}

sign = generate_sign(params, '2a1891544dbcf8e8b45b36d03187485a')
print(f"生成的签名: {sign}")
JavaScript 实现：
const crypto = require('crypto');

/**
 * 生成API签名
 * @param {Object} params - 业务参数对象（包含time）
 * @param {string} key - 分配的密钥
 * @returns {string} MD5签名字符串（小写）
 */
function generateSign(params, key) {
    // 获取排序后的参数键（排除sign）
    const sortedKeys = Object.keys(params)
        .filter(k => k !== 'sign')
        .sort();
    
    // 拼接参数字符串
    const paramString = sortedKeys
        .map(k => `${k}=${params[k]}`)
        .join('&');
    
    // 追加time和key
    const signString = `${paramString}&time=${params.time}&key=${key}`;
    
    // MD5加密并转小写
    return crypto.createHash('md5')
        .update(signString, 'utf8')
        .digest('hex')
        .toLowerCase();
}

// 使用示例
const params = {
    energyMode: '2',
    aiMode: '0',
    customTimes: '00:00,12:00,1000&13:00,15:00,-2000',
    batRatedCapacity: '1',
    batRatedChargingPower: '1000',
    dataTime: '2025-06-26',
    priceCompany: 'Germany',
    time: '1732756652'
};

const sign = generateSign(params, '2a1891544dbcf8e8b45b36d03187485a');
console.log('生成的签名:', sign);
C# 实现：
using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

public class SignGenerator
{
    public static string GenerateSign(Dictionary<string, string> parameters, string key)
    {
        // 排除sign字段，按key排序
        var sortedParams = parameters
            .Where(p => p.Key != "sign")
            .OrderBy(p => p.Key, StringComparer.Ordinal)
            .Select(p => $"{p.Key}={p.Value}");
        
        // 拼接参数
        string paramString = string.Join("&", sortedParams);
        
        // 追加time和key
        string signString = $"{paramString}&time={parameters["time"]}&key={key}";
        
        // MD5加密并转小写
        using (var md5 = MD5.Create())
        {
            byte[] hashBytes = md5.ComputeHash(Encoding.UTF8.GetBytes(signString));
            StringBuilder sb = new StringBuilder();
            foreach (byte b in hashBytes)
            {
                sb.Append(b.ToString("x2"));  // 转小写十六进制
            }
            return sb.ToString();
        }
    }
}

4. 发起 API 请求

• 请求头（Header）：必须携带 companyCode: {企业识别码} 与 Accept-Language: en-US。
• 请求体（Body）：除业务参数外，必须包含 time（与签名生成时完全一致的 UTC+0 秒级时间戳）和 sign（MD5 签名值）。

完整请求示例（cURL）：

curl --location 'https://api.aecc.com/openApi/price/setEnergyMode' \
--header 'companyCode: AECC2024001' \
--header 'Accept-Language: en-US' \
--header 'Content-Type: application/json' \
--data '{
  "energyMode": "2",
  "aiMode": "0",
  "customTimes": "00:00,12:00,1000&13:00,15:00,-2000",
  "batRatedCapacity": "1",
  "batRatedChargingPower": "1000",
  "dataTime": "2025-06-26",
  "priceCompany": "Germany",
  "time": "1732756652",
  "sign": "c3757db87150d5efbb45009d9253d375"
}'
完整请求示例（Java - HttpClient）：
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class ApiClient {
    
    private static final String API_URL = "https://api.aecc.com/openApi/price/setEnergyMode";
    private static final String COMPANY_CODE = "AECC2024001";
    private static final String KEY = "2a1891544dbcf8e8b45b36d03187485a";
    
    public static void main(String[] args) throws Exception {
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpPost httpPost = new HttpPost(API_URL);
        
        // 设置请求头
        httpPost.setHeader("companyCode", COMPANY_CODE);
        httpPost.setHeader("Accept-Language", "en-US");
        httpPost.setHeader("Content-Type", "application/json");
        
        // 准备业务参数
        long currentTime = System.currentTimeMillis() / 1000;  // UTC+0秒级时间戳
        TreeMap<String, String> params = new TreeMap<>();
        params.put("energyMode", "2");
        params.put("aiMode", "0");
        params.put("customTimes", "00:00,12:00,1000&13:00,15:00,-2000");
        params.put("batRatedCapacity", "1");
        params.put("batRatedChargingPower", "1000");
        params.put("dataTime", "2025-06-26");
        params.put("priceCompany", "Germany");
        params.put("time", String.valueOf(currentTime));
        
        // 生成签名
        String sign = SignGenerator.generateSign(params, KEY);
        params.put("sign", sign);
        
        // 构造JSON请求体
        JSONObject requestBody = new JSONObject();
        for (String key : params.keySet()) {
            requestBody.put(key, params.get(key));
        }
        
        httpPost.setEntity(new StringEntity(requestBody.toString(), "UTF-8"));
        
        // 发送请求
        String response = httpClient.execute(httpPost, response -> {
            int statusCode = response.getStatusLine().getStatusCode();
            String responseBody = EntityUtils.toString(response.getEntity());
            System.out.println("响应状态码: " + statusCode);
            return responseBody;
        });
        
        System.out.println("响应内容: " + response);
        httpClient.close();
    }
}
服务端验签流程：
服务端按以下步骤验证请求合法性：
身份校验：根据请求头中的 companyCode 查询对应的企业密钥

• 时间戳校验：验证 time 参数是否在允许的时间范围内（默认±5分钟），防止重放攻击
• 签名重算：按相同规则（参数排序→追加time和key→MD5加密）重新计算签名
• 签名对比：对比计算结果与请求中的 sign 值，完全一致方通过验证
• 业务处理：验证通过后执行业务逻辑并返回结果

⚠️ 安全须知：

• 签名有效期与时间戳强绑定，服务端会校验时间戳有效性，请勿缓存签名复用
• 密钥泄露需立即联系官方重置，避免造成安全隐患
• 建议在生产环境中启用HTTPS，确保传输层安全

核心接口调用示例

以下按「动态电价」与「设备服务」两类接口提供核心调用示例，覆盖签名生成、请求构造与响应解析全流程。

能源调控与分时电价

动态电价接口地址前缀为 POST /openApi/price/，包含设置能源模式、获取电价区域列表、查询电价、获取电价策略时间段 4 个接口。此类接口为纯服务端计算接口，不涉及具体设备：Body 无需传 deviceSn，由「业务参数 + time + sign」组成，业务参数随接口不同（如 priceCompany、dataTime、energyMode 等），参数值均为 JSON 字符串。请求头与设备接口一致（companyCode、Content-Type: application/json 必选）。

{
  "energyMode": "2",
  "aiMode": "0",
  "customTimes": "00:00,12:00,1000&13:00,15:00,-2000",
  "batRatedCapacity": "1",
  "batRatedChargingPower": "1000",
  "dataTime": "2025-06-26",
  "priceCompany": "Germany",
  "time": "1732756652",
  "sign": "c3757db87150d5efbb45009d9253d375"
}

{
  "dataTime": "2024-09-07",
  "priceCompany": "Germany",
  "mode": "0",
  "time": "1725677116",
  "sign": "e07b26034722d166e7f059cb728ab3fd"
}

逆变器 / 电表接口通用说明

设备接口地址前缀为 POST /openApi/device/。与电价接口不同，设备接口围绕具体设备展开：只需传递 deviceSn，不需要传设备型号代码（DTC），服务端根据授权的 deviceSn 自动路由并返回对应型号结构；查询接口 Body 只有 deviceSn + time + sign。查询接口（示例三、示例四，以及 getSetInfo）不要求设备在线；设置接口（示例五、示例六）要求设备在线，离线返回 result=20008。

本期开放 7 个电表型号，型号与设置的对应关系如下：

电表各型号字段概要：

各型号完整字段表见《AECC能管系统SDK-完整版》设备服务章节。

空业务数据：设备绑定关系存在但数据尚未上报时，接口可能返回 result=0 且 obj.deviceVo=null（obj.deviceSn、obj.dataLogSn 也可能为 null），属正常情况。处理顺序：先判断 result=0，再判断 obj 与 obj.deviceVo 是否为 null，最后读取业务字段。字段顺序不作为契约，必须按字段名解析 JSON。

{
  "deviceSn": "NB2548300T110CHAB",
  "time": "1725450897",
  "sign": "e83ba9c021edd831ae69033f77528ac5"
}

{
  "result": 0,
  "msg": "Request successfully.",
  "obj": {
    "deviceSn": "NB2548300T110CHAB",
    "dataLogSn": "AECCAA0437",
    "deviceState": 1,
    "deviceVo": {
      "serialNumber": "NB2548300T110CHAB",
      "ratedPower": 110.0,
      "mpptCount": 9,
      "stringCount": 18,
      "pvStartVoltage": 180.0,
      "gridVoltageType": 1,
      "mainSDPVersion": "V1.2.3"
    }
  },
  "data": null,
  "taskResult": null
}

{
  "result": 0,
  "msg": "请求成功!",
  "obj": {
    "deviceSn": "EXAMPLE-METER-SN",
    "dataLogSn": "EXAMPLE-DATALOG-SN",
    "deviceState": 0,
    "deviceVo": {
      "lineType": 1,
      "currentReverseSet": 0,
      "ctType": 23
    }
  },
  "data": null,
  "taskResult": null
}

{
  "deviceSn": "NB2548300T110CHAB",
  "time": "1725450897",
  "sign": "e83ba9c021edd831ae69033f77528ac5"
}

{
  "result": 0,
  "msg": "Request successfully.",
  "obj": {
    "deviceSn": "NB2548300T110CHAB",
    "dataLogSn": "AECCAA0437",
    "deviceState": 1,
    "deviceVo": {
      "runStatus": 1,
      "pvTotalPower": 0.0,
      "dailyPvGenEnergy": 717.2,
      "totalPvGenEnergy": 29884.8,
      "dailyGridConnectGenEnergy": 678.9,
      "totalGridConnectGenEnergy": 28431.2,
      "gridTotalActivePower": null
    }
  },
  "data": null,
  "taskResult": null
}

{
  "result": 0,
  "msg": "请求成功!",
  "obj": {
    "deviceSn": "EXAMPLE-METER-SN",
    "dataLogSn": "EXAMPLE-DATALOG-SN",
    "deviceState": 0,
    "deviceVo": {
      "ctAPhaseVoltage": 220.1,
      "ctBPhaseVoltage": 220.2,
      "ctCPhaseVoltage": 220.3,
      "ctAPhaseCurrent": 10.1,
      "ctBPhaseCurrent": 10.2,
      "ctCPhaseCurrent": 10.3,
      "ctThreePhaseTotalPower": 3000.6,
      "aphasePowerFactor": 0.99,
      "totalPowerFactor": 0.98,
      "frequency": 50.01,
      "forwardActiveEnergy": 123.45,
      "reverseActiveEnergy": 1.23,
      "totalActiveEnergy": 124.68,
      "ctType": 23
    }
  },
  "data": null,
  "taskResult": null
}

{
  "deviceSn": "NB2548300T110CHAB",
  "paramName": "pvStartVoltage",
  "paramValue": "179",
  "time": "1785461710",
  "sign": "<md5-sign>"
}

{
  "result": 0,
  "msg": "Setting successful.",
  "obj": {
    "pvStartVoltage": "179"
  },
  "data": null,
  "taskResult": null
}

{
  "deviceSn": "<your-deviceSn>",
  "paramName": "currentReverseSet",
  "paramValue": "1",
  "time": "<utc-second-time>",
  "sign": "<md5-sign>"
}

{
  "result": 0,
  "msg": "设置成功！",
  "obj": null,
  "data": null,
  "taskResult": null
}
关键规则：

{
  "deviceSn": "NB2548300T110CHAB",
  "object": "{\"underVoltProtectRecoverValue\":\"197\",\"overVoltProtectRecoverValue\":\"250\"}",
  "time": "1785462195",
  "sign": "<md5-sign>"
}

{
  "result": 0,
  "msg": "Setting successful.",
  "obj": {
    "underVoltProtectRecoverValue": "197",
    "overVoltProtectRecoverValue": "250"
  },
  "data": null,
  "taskResult": null
}

{
  "deviceSn": "<your-deviceSn>",
  "object": "{\"currentReverseSet\":\"1\"}",
  "time": "<utc-second-time>",
  "sign": "<md5-sign>"
}

{
  "deviceSn": "<your-deviceSn>",
  "object": "{\"transformerPolarityAdjustA1\":\"1\",\"transformerPolarityAdjustB1\":\"0\",\"transformerPolarityAdjustC1\":\"1\"}",
  "time": "<utc-second-time>",
  "sign": "<md5-sign>"
}

常见问题（FAQ）

Q1：签名计算总返回 sign 不匹配，如何排查？

服务端在收到请求后会按相同规则（业务参数按 Unicode 升序拼接 → 末尾追加 time 和 key → MD5 → 转小写）重算签名，并与请求体中的 sign 做精确比较（区分大小写、不做 trim）。任一环节不一致都会判定为签名异常，统一返回 result=10001, msg="Signature exception"。

注意：签名异常、时间戳过期、companyCode/time/sign 缺失在服务端会合并为同一个 10001 错误，无法仅凭 code 区分，需按以下步骤逐项排查。

排查步骤（按命中率从高到低）：

• 确认 sign 为 32 位小写 hex MD5 输出必须转成全小写。若使用了大写或 Base64 编码，比对必然失败。

// 正确：Spring DigestUtils 返回的就是 32 位小写
String sign = DigestUtils.md5DigestAsHex(text.getBytes(StandardCharsets.UTF_8));
确认参数拼接顺序与原文一致
业务参数名必须按 Unicode（字典序）升序 排列，建议直接用 TreeMap（Java）/ sorted()（Python）/ .sort()（JS）自动排序。拼出来的字符串应为 k1=v1&k2=v2&...&time=xxx&key=xxx。

• 确认 sign 和 time 不参与业务参数排序 排序拼接时只处理业务参数，time 固定追加在末尾、key 再追加在 time 之后。sign 字段本身不参与签名原文。
• 确认参数值原值拼接，不做 URL 编码、不去空格
• 参数值为空字符串时仍要参与签名（如 status=&time=...）。
• 含 &、:、, 等特殊字符（如 customTimes 字段）直接原值拼接，不要 URL encode。
• 参数值首尾的空格会被当作字符参与 MD5，与服务端不一致就会失败，确认前后端都没有意外 trim 或空格。
• 确认 key 用的是官方分配的原始密钥 服务端按请求头 companyCode 查库取 keySecret 拼到签名末尾。客户端必须使用同一份原始密钥，不得做任何编码/截断/转换。若疑似密钥泄露或记错，联系官方重置。
• 确认 time 在签名原文和请求体中完全一致 time 既要拼进签名原文，也要原值放进请求体。两者必须一字不差（同一秒级时间戳字符串），否则服务端按请求体里的 time 重算会得到不同的 sign。
• 本地复现服务端算法 把拼接好的待签名字符串打印出来，用任意在线 MD5 工具计算，与服务端期望值比对。若仍不一致，可把待签名原文 + 你的 sign 一并提供给官方协助定位。

服务端签名重算核心逻辑（参考实现）：

// 1. 业务参数按 TreeMap 字典序拼接（排除 sign 和 time）
// 2. 末尾追加 &time={time}&key={keySecret}
// 3. MD5(text.getBytes("UTF-8"))，结果为 32 位小写 hex
if (md5.equals(requestSign)) { /* 通过 */ }

Q2：时间戳有效范围是多少？如果服务器时间与标准时间有偏差怎么办？

• 时间戳格式：UTC+0 时区的秒级 Unix 时间戳（10 位数字，如 1732756652），不要使用毫秒级（13 位）或带时区的本地时间。
• 有效范围：服务端会取当前 UTC+0 秒级时间戳与请求中的 time 比较，允许偏差为 ±3600 秒（即 ±1 小时）。超出该窗口的请求会被判定为过期，返回 result=10001, msg="Signature exception"。

时间偏差处理建议：

• 以服务端为准：每次发起请求前实时生成 time = 当前 UTC+0 秒级时间戳，不要缓存复用历史时间戳，因为签名与时间强绑定。
• 校准服务器时钟：若你的服务器时间与标准时间（NTP）偏差超过几十秒，建议启用 NTP 时钟同步（如 Linux 的 ntpd/chrony、Windows 的 w32time），避免长期运行后时钟漂移导致请求被拒。
• 不要尝试放宽窗口：±1 小时是服务端固定策略，无法由客户端调整；偏差超过 1 小时只能校准时钟。
• 容器/云环境注意：Docker 容器、虚拟机重启后偶发时钟回退，建议在容器启动时同步一次时间。

Q3：key 是否可以放在请求头或 URL 中传递？

不可以。 key（密钥）严禁以任何形式出现在网络请求中。

• key 的唯一用途：仅在客户端本地参与签名计算（拼接待签名原文末尾的 &key=xxx），其本身不作为请求参数、不放在 header、不放在 URL query。
• 服务端获取方式：服务端根据请求头中的 companyCode 查询数据库，取出对应的 keySecret 来重算签名。也就是说 companyCode 是身份标识（会随请求传输），key 是对应的密钥（仅在两端各自保存，不在网络中明文传输）。

正确做法：

• companyCode 放在请求头：--header 'companyCode: AECC2024001'
• key 仅在本地代码中参与 MD5，不进入任何请求字段。
• 安全要求：密钥应存储在服务器端配置文件或环境变量中，禁止硬编码到客户端、禁止打印到日志、禁止随请求外发。一旦怀疑泄露，立即联系官方重置。

Q4：接口超时或返回 5xx 错误时应该如何处理？

开放接口的 HTTP 层基本固定返回 200，业务结果通过响应体的 result 字段表达；真正的系统级异常会统一映射为 result=4000, msg="System error, please contact the administrator!"。建议按以下策略处理：

1. 客户端超时设置

建议为每次调用设置合理的连接和读取超时（如连接 5s、读取 10s），避免因网络抖动导致线程长时间阻塞：

// HttpClient 示例
RequestConfig config = RequestConfig.custom()
        .setConnectTimeout(5000)      // 连接超时 5s
        .setSocketTimeout(10000)      // 读取超时 10s
        .build();
HttpPost httpPost = new HttpPost(url);
httpPost.setConfig(config);
2. 针对 result=4000（系统错误）的重试

• 这类错误通常是服务端临时故障，可重试。
• 建议指数退避重试：间隔 1s → 2s → 4s，最多 3 次；重试时务必重新生成 time 和 sign，不要复用原请求。
• 若持续返回 4000，联系官方并提供 companyCode、请求时间、deviceSn/接口路径。

3. 针对网络超时（无响应）的处理

• 客户端抛出 SocketTimeoutException / 连接被拒时，同样按指数退避重试。
• 若连续多次超时，先排查本机网络与 DNS，再联系官方确认服务状态。

4. 不要重试的情况

• result=10001（签名异常）：重试不会改变结果，需先修正签名/时间戳。
• result=20001（参数为空）/ 20004（参数格式错误）/ 2000x 类业务校验错误：修正参数后再发。
• result=10006（账号被禁用）/ 20002（权限异常，含凭证不存在/未启用）：联系官方处理。

5. 限流

部分接口配置了接口请求限流。触发限流时会通过全局异常返回错误信息，客户端应降低调用频率，不要立即重试。

Q5：响应中的 code 和 msg 字段含义在哪里查看？

说明：响应体中的状态字段实际命名为 result（而非 code），下文为便于理解统一按"状态码"描述。

响应结构：

{
  "result": 0,
  "msg": "Request successfully.",
  "data": { /* 业务数据 */ }
}

• result：状态码，0 表示成功，非 0 表示失败。
• msg：状态描述文本，支持国际化（i18n），语言由请求头 Accept-Language 决定（如 en-US、zh-CN），未传时默认 en-US。
• data / obj：业务数据载体，成功时返回具体业务对象。

常见状态码对照表：

排查建议：

• 调用时记录完整的 result、msg 以及请求参数，便于定位。
• 若 msg 为英文且希望查看中文，可将 Accept-Language 改为 zh-CN。