---
title: "什么是幂等键（Idempotency Key）？API 安全重试详解 | BroadRouter"
description: "幂等键是客户端随请求发送的唯一 ID，确保重试不会重复产生效果，比如重复扣款。它的工作原理，以及 IETF 的 Idempotency-Key 请求头。"
url: https://broadrouter.com/zh/glossary/idempotency-key/
lang: zh-Hans
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。 [阅读英文原文](https://broadrouter.com/glossary/idempotency-key/) (2026-11-14 更新).

# 幂等键（idempotency key）

更新于 2026-11-14

幂等键是客户端附在会改变状态的请求（如付款或购买）上的唯一值，通常是 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，除非提供幂等性，否则重试并不安全。）

## 为什么重要

配合[指数退避](https://broadrouter.com/zh/glossary/exponential-backoff/)重试是标准做法，很多 SDK 还会自动重试。没有幂等性，超时后的一次重试就可能生成两笔订单或两次扣款。有了幂等键，不管第一次尝试做了什么，重试都是安全的。对于无人值守、会购买、预订或创建资源的智能体和脚本来说，这是一项核心工具。

## 在 BroadNet Inference 上

BroadNet 在购买[按小时密钥](https://broadrouter.com/zh/blog/hourly-llm-api-key-explained/)时使用这种模式。`POST /portal/keys/hourly` 在 JSON 请求体中接收 `request_id`，文档写明 “Idempotency is required for money safety”（译文：为了资金安全，必须保证幂等）：

```bash
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` 或转写接口记录幂等键。哪些情况该重试，参见[错误码与重试](https://broadrouter.com/zh/guides/errors-and-retries/)；盲目重试为什么会让 429 更严重，参见[速率限制](https://broadrouter.com/zh/glossary/rate-limit/)。

## 常见问题

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

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

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

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

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

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

## 另请参阅

-   [指数退避（exponential backoff）](https://broadrouter.com/zh/glossary/exponential-backoff/) (术语)
-   [速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/) (术语)
-   [API 密钥（API key）](https://broadrouter.com/zh/glossary/api-key/) (术语)
-   [并发（concurrency）](https://broadrouter.com/zh/glossary/concurrency/) (术语)
-   [BroadNet Inference 错误码，以及什么时候该重试](https://broadrouter.com/zh/guides/errors-and-retries/) (指南)
-   [用 IP 白名单把 API 密钥锁定到你的服务器](https://broadrouter.com/zh/guides/api-keys-ip-allow-lists/) (指南)
-   [长时间运行的智能体：可靠的超时、重试与检查点](https://broadrouter.com/zh/blog/long-running-agents-timeouts-retries/) (文章)
-   [按小时计费的大模型 API 密钥：每小时固定价格详解](https://broadrouter.com/zh/blog/hourly-llm-api-key-explained/) (文章)

用你的真实业务负载试一试。 新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-glossary-idempotency-key&utm_content=page-cta) ·

**来源**

-   [IETF HTTPAPI：The Idempotency-Key HTTP Header Field（互联网草案）](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders' Library：超时、重试与带抖动的退避（幂等 token）](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [BroadNet Inference API 参考：按小时密钥（request\_id 幂等） （英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-glossary-idempotency-key&utm_content=sources#hourly-keys)
