频率限制
每个接口都有频率限制。限制按账户计算(同一账户下的所有 APP Key 和控制台会话共用一份额度),分每秒和每分钟两个窗口。某个接口的具体数值见其页面的 限制说明。 每个账户的默认限制:
部分接口的限制更严,例如导出和较重的统计分析查询,以其 限制说明 中的数值为准。
触发限制时
请求返回 HTTP429 和错误码 RequestTooFrequently,响应头 Flashcat-Request-Rate-Limit-Delay 给出距当前窗口重置还有多少秒。请至少等待这么久再重试;没有该响应头时按指数退避(1 秒、2 秒、4 秒……)。
权限校验
- 全部权限的 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,技术支持需要它来定位请求。