跳转到主要内容

频率限制

每个接口都有频率限制。限制按账户计算(同一账户下的所有 APP Key 和控制台会话共用一份额度),分每秒和每分钟两个窗口。某个接口的具体数值见其页面的 限制说明。 每个账户的默认限制: 部分接口的限制更严,例如导出和较重的统计分析查询,以其 限制说明 中的数值为准。

触发限制时

请求返回 HTTP 429 和错误码 RequestTooFrequently,响应头 Flashcat-Request-Rate-Limit-Delay 给出距当前窗口重置还有多少秒。请至少等待这么久再重试;没有该响应头时按指数退避(1 秒、2 秒、4 秒……)。
在循环里立即重试只会让窗口一直处于打满状态。批量任务请分散执行,并优先使用一次可传多个 ID 的接口,而不是逐个对象调用。

权限校验

  • 全部权限的 APP Key 不额外限制接口范围,但仍受创建者当前角色权限约束。
  • 自定义权限的 APP Key 只能调用选中的接口范围。
  • 超出 APP Key 权限范围或创建者角色权限的调用返回 HTTP 403 和 AccessDenied。每个接口所需权限见其页面的 限制说明。
  • 部分接口还会校验对象级权限(例如只有协作空间所属团队的成员才能修改它),具体规则写在接口页面的 使用说明 中。
  • 建议按用途分别创建 APP Key,每个只授予所需的最小范围。

错误码

所有失败响应都使用 { "request_id": "…", "error": { "code": "…", "message": "…" } } 结构。请以稳定的 error.code 做判断;message 会按语言变化,也可能调整措辞。 API 参考中 ErrorCode 枚举的其他取值(RequestVerifyRequired、DangerousOperation、RequestLocked、BalanceNotEnough、UndonedOrderExist)只用于 MFA、计费等控制台流程,Open API 接口不会返回。

重试建议

  • 只重试 429、500、503 和网络错误,使用指数退避(从 1 秒开始,最多重试 3 次)。429 请遵循 Flashcat-Request-Rate-Limit-Delay。
  • 不要原样重试其他 4xx 错误,结果不会改变。
  • **创建类接口按非幂等处理。**创建请求超时后重试前,先通过列表或查询接口确认上一次是否已经成功。
  • 记录失败调用的 request_id,技术支持需要它来定位请求。