错误模型

适用范围

/api/v1/open/ 下所有开放平台 API 接口都遵循同一套错误结构。

{
  "code": "VALIDATION_FAILED",
  "message": "invalid request payload",
  "request_id": "req-123"
}

code	HTTP	说明
`INVALID_REQUEST_BODY`	400	JSON 请求体无法解析
`VALIDATION_FAILED`	400	请求字段缺失、类型非法、非 JSON 对象或超出范围
`IDEMPOTENCY_CONFLICT`	409	`idempotency_key` 与之前请求体不一致（同 key 不同 body）
`COMMAND_NOT_FOUND`	404	`command_id` 不存在
`DEVICE_REQUEST_NOT_FOUND`	404	`request_id` 不存在
`UNSUPPORTED_VENDOR`	400	001 命令受理中厂商未注册
`UNSUPPORTED_COMMAND`	400	001 命令受理中命令类型不受支持或不在可信能力范围内
`OBJECT_POLICY_DENIED`	403	对象预签名请求不满足租户资源策略
`OBJECT_SIGNING_FAILED`	500	对象存储预签名失败
`CALLBACK_NOT_FOUND`	404	callback endpoint 或 subscription 不存在
`NATS_PRINCIPAL_CONFLICT`	409	NATS principal 已存在冲突
`NATS_SUBJECT_POLICY_INVALID`	400	NATS subject 未按租户前缀授权或策略非法
`INTERNAL_ERROR`	500	平台内部错误，附 `request_id` 后联系技术支持

鉴权失败也返回上面的标准结构。

code	HTTP	说明
`UNAUTHORIZED`	401	未认证：缺少 API ID、timestamp、nonce、signature，或凭据不可用
`SIGNATURE_INVALID`	401	签名无效：签名值不匹配，可能是 API Key 错、canonical 串拼接错、或请求体被代理改写
`TIMESTAMP_EXPIRED`	401	时间戳过期：`X-Api-Timestamp` 超出平台允许的偏差窗口
`NONCE_REPLAYED`	401	nonce 在重放窗口内重复使用
`FORBIDDEN`	403	当前 API client 没有租户域内权限
`TENANT_NOT_FOUND`	401	无法解析有效租户，或租户已禁用/删除
`TENANT_BINDING_INVALID`	403	API client 与租户绑定关系无效

业务错误：

{
  "code": "UNSUPPORTED_VENDOR",
  "message": "vendor is not supported",
  "request_id": "req-unsupported"
}

鉴权错误：

{
  "code": "SIGNATURE_INVALID",
  "message": "invalid signature",
  "request_id": "req-signature"
}