网络总在最糟的地方断开:服务器已经执行,你却还没收到响应。幂等键让这时的重试变得安全。
原理
客户端为一个预期的操作生成唯一的键,随请求一起发送。服务器把键和结果一起保存。同一个键再次到达时,服务器重放保存的结果,而不是再执行一次。
IETF HTTPAPI 工作组正在把它标准化为 Idempotency-Key 请求头(草案第 08 版,2026 年 10 月,尚未成为 RFC)。草案把这个键描述为 “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request”(译文:由客户端生成的唯一值,资源用它来识别同一请求的后续重试),并建议使用 UUID 或类似的随机 ID。草案定义的错误情况:
| 情况 | 状态码 |
|---|---|
| 要求提供键却缺失 | 400 Bad Request |
| 原请求仍在处理中 | 409 Conflict |
| 同一个键配了不同的请求体 | 422 Unprocessable Content |
AWS 的 Builders’ Library 从客户端角度说了同样的道理:“APIs with side effects aren’t safe to retry unless they provide idempotency.”(译文:有副作用的 API,除非提供幂等性,否则重试并不安全。)
为什么重要
配合指数退避重试是标准做法,很多 SDK 还会自动重试。没有幂等性,超时后的一次重试就可能生成两笔订单或两次扣款。有了幂等键,不管第一次尝试做了什么,重试都是安全的。对于无人值守、会购买、预订或创建资源的智能体和脚本来说,这是一项核心工具。
在 BroadNet Inference 上
BroadNet 在购买按小时密钥时使用这种模式。POST /portal/keys/hourly 在 JSON 请求体中接收 request_id,文档写明 “Idempotency is required for money safety”(译文:为了资金安全,必须保证幂等):
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
-H "Authorization: Bearer <portal-credential>" \
-H "Content-Type: application/json" \
-d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
重复使用同一个 request_id 不会创建新密钥,也不会再扣费。遇到超时、连接中断、409 mint_in_progress 或 5xx 时,用同一个 request_id 重试。重放的响应会返回 already_issued: true 和密钥的别名;只有第一次成功的响应包含原始密钥。文档写道:“Never generate a replacement id until the original result is known.”(译文:在知道原始结果之前,绝不要生成替代 id。)
BroadNet 没有为 /v1/chat/completions 或转写接口记录幂等键。哪些情况该重试,参见错误码与重试;盲目重试为什么会让 429 更严重,参见速率限制。