限流与重试

OpenAPI 对 REST API 请求实施限流，防止单个客户端过度消耗资源；本页说明限流策略和客户端重试建议。

限流规则

• OpenAPI 服务触发限流时返回 429 RATE_LIMITED
• 429 响应会包含 Retry-After 响应头，单位为秒
• Retry-After 的值为正整数，表示建议等待多少秒后再次请求

Idempotency-Key

Idempotency-Key 是调用方为一次命令请求生成的唯一请求键。

它用于处理网络超时或重试场景：如果客户端不确定命令请求是否已经被 OpenAPI 接收，可以使用同一个 Idempotency-Key 重试同一请求，避免重复创建命令。

使用规则：

• 每次新的命令请求应生成新的 Idempotency-Key
• 同一次命令请求的重试应复用原来的 Idempotency-Key
• 同一个 Idempotency-Key 不应复用于不同设备、不同继电器或不同请求体
• Idempotency-Key 不是访问令牌，也不用于身份认证

客户端重试规则

• 客户端收到 429 后，应等待 Retry-After 指定的时间后再重试
• 客户端收到 500 INTERNAL_ERROR 时，可使用指数退避重试
• 对有副作用的命令接口，重试必须复用同一个 Idempotency-Key
• 客户端应使用有上限的重试并加入随机抖动，避免紧密重试循环
• 遇到 400、401、403、404、409 或 422 时，不应在不修改请求或凭证的情况下重试

限流响应示例

HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit: limit=1, remaining=0, reset=3

{
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "requestId": "req_001",
  "data": {
    "retryAfterSeconds": 3
  }
}

retryAfterSeconds 与 Retry-After 响应头的值相同，单位为秒。