速率限制

速率限制按账号计算，分为两个互相独立的桶。一次请求只消耗自己那一类桶的额度，所以频繁轮询不会占用创建任务的额度。

桶	默认额度	覆盖接口
写操作	20 次 / 10 秒	POST /v1/tasks、POST /v1/storages/promote、POST /v1/storages/delete
读操作	60 次 / 10 秒	GET /v1/tasks、GET /v1/tasks/:id、GET /v1/storages

• 两个桶都用 10 秒滑动窗口，按用户计数而不是按 API Key：同一账号下的多个 Key 共用一个额度
• 用 GET /v1/tasks/:id 轮询只计入读桶，不消耗写额度，正常轮询不会影响提交任务
• 请求只要到达接口就计数，包括随后被 4xx 拒绝的请求（如请求体格式错误）；提交失败后重试同样消耗写额度
• 在限流检查之前就被拒绝的请求（如 API Key 缺失或无效的 401）不计数
• 除请求频率外，平台通常可同时运行 100+ 个任务

速率限制不是并发上限

速率限制控制的是新任务的提交速度，不是正在排队或运行的任务数量。已进入队列或正在运行的任务不会占用后续时间窗口的请求额度；实际执行速度仍取决于所选模型和服务容量。

超过限制时

某个桶的额度用完后：

• 请求会被拒绝，并返回 HTTP 429
• 响应包含 Retry-After，值为限流窗口的秒数
• 响应错误码为 RATE_LIMITED
• 被拒绝的请求不会进入任务队列

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>
Content-Type: application/json

{"code":429,"message":"too many requests, retry later","data":null,"error_code":"RATE_LIMITED"}

响应不带 X-RateLimit-* 头，无法提前读取剩余额度；Retry-After 只在 429 时出现。

客户端应等待 Retry-After 指定的时间后再重试，并使用指数退避和随机抖动避免集中重试。

申请更高限制

如果持续收到 HTTP 429，可以联系 HiAPI 支持团队申请更高的账户请求限制。平台会根据实际使用场景、请求模式和账户情况进行评估。