响应格式

所有 REST API 都返回 JSON。 客户端应同时读取 HTTP 状态码和响应体中的 code。

字段说明

字段	类型	必填	说明
code	string	是	业务码。成功类和错误类都使用大写下划线格式
message	string	是	人类可读说明，仅用于展示、日志和排障
requestId	string	是	请求编号，排障时需要提供
data	object	视响应而定	成功数据，或错误处理所需的结构化信息

客户端处理规则

• 客户端必须基于 HTTP status 和 code 做程序分支
• 客户端不能基于 message 做程序分支
• message 仅用于展示、日志和排障上下文，不适合作为程序判断条件

成功类响应

下面示例仅展示统一响应外层结构。data 内的具体字段以各接口文档为准。

{
  "code": "SUCCESS",
  "message": "OK.",
  "requestId": "req_001",
  "data": {
    "example": "..."
  }
}

失败响应

多数失败响应省略 data：

{
  "code": "AUTH_INVALID",
  "message": "Invalid access token.",
  "requestId": "req_001"
}

当客户端需要结构化信息才能修复问题时，失败响应可以包含 data。例如权限不足：

{
  "code": "AUTH_SCOPE_DENIED",
  "message": "This operation requires the device:control permission. Update the API Client permissions in the Developer Console and obtain a new access token.",
  "requestId": "req_001",
  "data": {
    "requiredScope": "device:control"
  }
}

使用说明

• 成功响应包含 data
• 多数失败响应省略 data；需要提供重试或修复信息时可以包含 data
• COMMAND_ACCEPTED 属于成功类业务码，响应中会包含 data