当 HiAPI 网关返回 HTTP 429 Too Many Requests 时，说明你所用的 API Key 在短时间内超过了它在 https://api.hiapi.ai/v1/tasks（或轮询端点 GET /v1/tasks/{taskId}）上被允许的请求频率或并发上限。响应体沿用 HiAPI 统一的错误信封——{"error":{"type":"hiapi_error","code":"...","request_id":"..."}}——并配一个 429 状态码。解决它几乎从来不需要给客服发邮件，而是在客户端加一层很小的「重试 + 限流」逻辑。本文讲清这个错误是什么、为什么会触发，以及让它消失的具体步骤。
HiAPI 429 长什么样
一次典型的请求在网络层大致是这样：
> POST /v1/tasks HTTP/1.1
> Host: api.hiapi.ai
> Authorization: Bearer hi-sk-...
> Content-Type: application/json
< HTTP/1.1 429 Too Many Requests
< Content-Type: application/json
<
{"error":{"type":"hiapi_error","code":"rate_limit_exceeded","request_id":"req_..."}}
两个要点：
- 状态码是
429，不是401/403。401表示 Key 不对或缺失；429表示 Key 没问题，只是你发得太快。两者别混为一谈。 - 响应体是
hiapi_error信封里的 JSON。 有些 HTTP 客户端默认只暴露状态码；如果你的代码在不打日志的情况下静默重试，就会丢掉request_id这类排查线索。
如果你调用的是 GPT Image 2、Nano-Banana、flux、Seedance、Wan 或 HappyHorse 这些模型，它们全部跑在同一个异步任务端点上，因此共用同一个 Key 维度的速率计费。
常见原因（按命中概率排序）
按我们的经验，从高到低大致是：
- 单 Key 的突发扇出（burst fan-out）。 你遍历一批 prompt，对每个都并发调
POST /v1/tasks，又没有并发上限。哪怕只是十来个并发的任务创建，在一个新账号上就足以触顶。 - 对
GET /v1/tasks/{taskId}的激进轮询。 一个while True: poll(); sleep(0.2)的紧循环，和创建任务一样算作请求量。亚秒级轮询是「我只建了一个任务却还是 429」的头号原因。 - 账号级并发上限。 偏重的模型——视频（
seedance-2.0、wan2.7-video/*、happyhorse-1.0）和@pro图像变体——计入更严格的并发任务上限。一次性提交很多这类任务，即便你的每分钟频率不高也会 429。 - 一个 Key 跨多个环境共用。 dev、staging、prod 都用同一个
HIAPI_API_KEY，量会叠加。每个环境单看都没事，加在一起就把 Key 推过了上限。 - 套餐额度耗尽。 免费额度或接近用尽的付费套餐，有时会表现为 429 而非计费错误，尤其在促销期间。
关于具体阈值：HiAPI 的每分钟请求数与并发上限以你的账户档位为准，平台并不对外公布一个固定数字。所以下面给的并发值（5、3、2）是经验起点，而非官方限额——请结合仪表盘里的真实用量来调。
修复步骤
按顺序做。大多数团队做到第 3 步就不再被告警叫醒了。
1. 加带抖动的指数退避
任何与 api.hiapi.ai 通信的客户端，遇到 429 都应该用递增的延迟重试——绝不要立即重试。一个安全的默认实现：
import random, time, requests
def post_task_with_backoff(body, key, *, max_retries=5):
delay = 1.0
for attempt in range(max_retries):
r = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=body, timeout=30,
)
if r.status_code != 429:
r.raise_for_status()
return r.json()
retry_after = r.headers.get("Retry-After")
wait = float(retry_after) if retry_after else delay + random.random()
time.sleep(min(wait, 30.0))
delay = min(delay * 2, 30.0)
raise RuntimeError("rate-limited after retries")
这段代码做对了两件事：把延迟封顶在 30 秒；以及在存在 Retry-After 响应头时优先采用它。即便你这次的 429 响应里没有 Retry-After，「封顶 + 抖动」的策略也足以消化掉大多数突发。
2. 按 Key 限制客户端并发
在客户端加一个信号量（semaphore）是单项最有效的改动。如果不知道取多少，从 5 开始：
import asyncio, httpx
sem = asyncio.Semaphore(5)
async def create_task(client, body):
async with sem:
r = await client.post("https://api.hiapi.ai/v1/tasks", json=body, timeout=30)
return r.json()
同时在跑 5 个任务，对多数账号都很从容。如果还是 429，降到 3。重型视频模型通常需要一个单独、更低的信号量（试试 2）。
3. 从轮询切换到 callback.url
对生产负载来说，轮询 GET /v1/tasks/{taskId} 不是个好默认。在请求体里传 callback.url，HiAPI 会在任务到达终态时把结果 POST 给你：
{
"model": "Nano-Banana",
"input": { "prompt": "a calm lake at dawn", "aspect_ratio": "16:9" },
"callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}
这把 O(任务数 × 轮询次数) 的请求模式压成 O(任务数)——通常是 10–50 倍的调用量下降，也是轮询型 429 近乎立竿见影的解药。把 GET /v1/tasks/{taskId} 留给本地调试和低频的一次性调用即可。
4. 放慢轮询节奏并加抖动
如果你用不了回调（离线脚本、本地 notebook、兜底对账），那就别比每 2–5 秒更快地轮询，并加上抖动，避免多个 worker 齐步走：
import random, time
time.sleep(2 + random.random() * 3) # 2–5 秒，带抖动
5. 按环境拆分 Key
在 HiAPI API 密钥页 为每个环境各生成一个 Key——dev、staging、prod。每个环境的突发互相隔离，而且某个 Key 泄漏了也能单独吊销，不影响其他环境。
6. 查当前用量
打开 HiAPI 仪表盘 确认你撞的是并发/套餐上限，还是只是一次短暂的突发；各档套餐的额度可在定价页对照。如果用量远低于套餐却仍然 429，那原因几乎肯定是客户端侧的突发，而不是账号本身。
最小验证
重试层就绪后，用一个 Nano-Banana 任务是确认链路通不通最便宜的方式。把 $HIAPI_API_KEY 换成你的 Key：
curl -s -X POST https://api.hiapi.ai/v1/tasks \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Nano-Banana",
"input": { "prompt": "a single red apple on a white table", "aspect_ratio": "1:1" }
}'
成功大致长这样：{"code":200,"data":{"taskId":"tk-hiapi-..."}}。然后轮询一次：
curl -s -H "Authorization: Bearer $HIAPI_API_KEY" \
https://api.hiapi.ai/v1/tasks/tk-hiapi-...
状态会经过 queued → handling → archiving → success，最终的 data.output[0].url 就是你的图。如果这一个来回返回 200、但你的批量任务仍然 429，那问题出在客户端的并发上，而不是你的 Key。
常见问题
我明明只发了一个请求，为什么还会 429？
几乎总是因为真正的请求量来自轮询循环，而不是任务创建。对 5 个并发任务做 200ms 间隔的轮询，光这一项就是每秒 25 个请求。把轮询放慢到 2–5 秒，或改用 callback.url。
HiAPI 一定会带 Retry-After 响应头吗？
把 Retry-After 当作建议值：有就用它，没有就回退到指数退避（1s、2s、4s……封顶 30s）。无论哪种，都别不加延迟就重试——那只会把突发放得更大。
429 和 401 / 403 是一回事吗？
不是。401 / 403 表示鉴权失败，走同一个 hiapi_error 信封，例如 {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"req_..."}}（实测 401 的 message 会提示 “This API key is invalid. Check that it is correct...”）。如果你看到 401/403，去 API 密钥页 核对 Key 的值——退避救不了它。
我能直接把速率上限调高吗？
如果你的流量确实需要更高的并发上限，先在定价页确认套餐额度，再从那里联系客服。实践中，上面这些修复能在不改任何上限的情况下解决 90% 以上的 429 问题。
/v1/tasks 上的 429 和 /v1/tasks/{taskId} 上的 429 有什么区别？
端点只是告诉你当时在做什么——两者共用同一个 Key 维度的速率预算。创建接口的 429 指向扇出（限制并发、改批处理）；轮询接口的 429 指向紧轮询循环（放慢节奏或切回调）。完整的请求/响应结构见 HiAPI Quickstart 和认证文档。
小结
429 是任何生产级 API 网关都会给出的正常、可恢复信号。加上指数退避、限制客户端并发、用回调替代轮询，并在仪表盘确认用量。这四件事做到位之后，你就可以彻底不再去想 429 了。本页是英文原文《How to Fix HiAPI Rate Limit (429) Errors》的简体中文版，技术细节与原文保持一致。
