Idempotency-Key 请求头
使用 Idempotency-Key 重试请求，不会创建重复操作。该机制保证恰好一次受理：在 3 小时保留期内，使用相同密钥且请求完全相同的重试必须解析为原始操作，即使您丢失了原始响应。重试策略请参阅幂等性。
请求头
| 请求头 | 约束条件 |
|---|---|
Idempotency-Key | 可选。最多 255 个字符的任意非空字符串；建议使用 UUID v4。适用于受支持的 POST、PATCH、PUT 和 DELETE 操作；GET、HEAD 和 OPTIONS 会忽略该请求头。 |
以工作区或组织为作用域的修改操作支持下文所述的响应重放。仅以用户为作用域的操作、没有作用域的未认证操作，以及流式操作不使用此机制。有独立重放约定的操作会在各自的参考页面中定义其行为。
省略请求头或发送空值时，请求会正常处理，不进行去重。对于声明了此请求头的端点，超过 255 个字符的密钥会返回 422，错误代码为 E01001 ValidationError。
密钥的作用域是您的工作区；对于组织级端点，作用域是您的组织。密钥会保留约 3 小时。保留期结束后，复用该密钥的请求会作为新请求处理。
响应语义
| 场景 | 响应 |
|---|---|
| 首次使用某密钥的请求 | 正常处理；已完成的响应可以保留以供重放；5xx 响应不会保留。 |
| 相同密钥，保留期内的相同请求 | 原始操作；已保留的响应会重放，并附带 Idempotency-Replay: true。 |
| 相同密钥，不同请求 | 返回 409，错误码为 E01005 IdempotencyKeyReuse。请为新请求生成新密钥。 |
| 相同密钥，原始请求仍在处理中 | 返回 409，错误码为 E01004 RequestInProgress。请等待，然后使用相同的密钥和相同的请求重试。 |
原始请求返回了 5xx | 错误响应不会保留。请使用相同的密钥和相同的请求重试。 |
| 幂等性保护在执行前不可用 | 返回 503，错误码为 E01033 IdempotencyUnavailable。本次尝试未被执行；使用相同的密钥和请求重试。 |
重放的响应与原始响应逐字节一致（相同状态码、相同响应体），仅通过额外的响应头加以区分：
HTTP/1.1 202 Accepted
Idempotency-Replay: true"Identical request" 涵盖方法、端点、路径和查询参数，以及原始请求体。这些值存在差异时，包括 JSON 中的空白字符差异，都会触发 E01005。分段上传会比较各部分的名称、文件名和内容；边界分隔符和各部分的顺序不影响重放。这两种 409 错误都使用标准错误响应格式返回。
保留的响应可能包含 4xx 拒绝响应。修正请求时请使用新密钥：如果拒绝响应已保留，未修改的重试会重放该响应，而修改后的请求会返回 409 E01005 IdempotencyKeyReuse。
遇到超时或 5xx 时，请在三小时内使用相同的密钥和相同的请求进行有限次数的退避重试。即使原始响应已丢失，恰好一次受理的保证依然适用。E01033 IdempotencyUnavailable 表示本次尝试未被执行；它并不描述先前某次尝试的结果。每次重试都保留该密钥。
对于消息发送，恰好一次受理意味着在所有匹配的重试中只会受理一次发送。请检查消息状态以确认是否送达。三小时后，请先检查原始操作的结果再重新提交：已过期的密钥或新密钥可能会创建另一个操作。
SDK 行为
官方 SDK 会为每个变更请求附加一个自动生成的 UUID Idempotency-Key，该值在每次逻辑调用时生成一次，并在该调用的所有重试尝试中复用。当一个逻辑操作跨越多个 SDK 调用时，您可以为每次调用提供自己的密钥（TypeScript 中为 idempotencyKey，Go 中为 option.WithIdempotencyKey，Python 中为 idempotency_key，PHP 中为 new RequestOptions(idempotencyKey: ...)）。要检测重放，请通过各 SDK 的传输元数据访问器读取 Idempotency-Replay 响应头：TypeScript 中为 .withResponse()，Go 中为 option.WithResponseInto，Python 中为 with_raw_response。