BroadRouter
开始使用

幂等键(idempotency key)

更新于

幂等键是客户端附在会改变状态的请求(如付款或购买)上的唯一值,通常是 UUID 之类的随机 ID。如果用同一个键再次发送同一请求,服务器会返回原来的结果,而不会把操作执行两次。

又称: 幂等键、幂等性、幂等请求、幂等重试、幂等 token、Idempotency-Key 请求头、idempotency key、Idempotency-Key header、idempotency token、idempotent request、idempotent retry

网络总在最糟的地方断开:服务器已经执行,你却还没收到响应。幂等键让这时的重试变得安全。

原理

客户端为一个预期的操作生成唯一的键,随请求一起发送。服务器把键和结果一起保存。同一个键再次到达时,服务器重放保存的结果,而不是再执行一次。

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 更严重,参见速率限制。

常见问题

什么时候该生成新的幂等键?

只在发起一个新的操作时。同一个操作的每次重试都用同一个键;在知道第一次尝试的结果之前,不要生成新键。

大模型的对话补全请求需要幂等键吗?

生成文本没有持久的副作用,所以重复的对话请求通常只是再花一次 token。幂等键对会扣费或创建资源的调用才重要。BroadNet 只为购买按小时密钥记录了它,对话补全没有。

用同一个键发送不同的请求体会怎样?

IETF 草案说服务器应当以 422 Unprocessable Content 拒绝,因为这个键已经绑定到另一个请求。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity