Idempotency-Key 请求头
Bird API 支持通过 Idempotency-Key 请求头选择启用请求去重。本页定义 HTTP 协议约定；重试策略请参阅幂等性。
请求头
| 请求头 | 约束条件 |
|---|---|
| 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。锁会在约 30 秒内过期；等待后重试。 |
| 原始请求返回了 5xx | 不缓存：密钥解锁，重试将作为全新请求处理。 |
| 幂等性保护在执行前不可用 | 返回 503，错误码为 E01033 IdempotencyUnavailable。本次尝试未被执行；使用相同的密钥和请求重试。 |
重放的响应与原始响应逐字节一致（相同状态码、相同响应体），仅通过额外的请求头加以区分：
代码示例
HTTP/1.1 202 Accepted
Idempotency-Replay: true"Identical request" 涵盖方法、端点、路径和查询参数，以及原始请求体。这些值存在差异时，包括 JSON 中的空白字符差异，都会触发 E01005。分段上传会比较各部分的名称、文件名和内容；边界分隔符和各部分的顺序不影响重放。这两种 409 错误都使用标准错误响应格式返回。
保留的响应可能包含 4xx 拒绝响应。修正请求时请使用新键：如果拒绝响应已保留，未修改的重试会重放该响应，而修改后的请求会返回 409 E01005 IdempotencyKeyReuse。
5xx 响应永远不会被缓存。使用相同的密钥和请求进行退避重试。E01033 IdempotencyUnavailable 表示本次尝试未被执行；它并不描述先前某次尝试的结果。每次重试都保留该密钥。
操作可能在其响应被保留之前就已生效。如果该响应丢失，或处理中的锁过期，重试可能会再次执行该操作。因此，超时或另一个 5xx 响应并不能证明操作没有产生效果。
SDK 行为
官方 SDK 会为每个变更请求附加一个自动生成的 UUID Idempotency-Key，每次逻辑调用生成一次，并在该调用的所有重试尝试中复用。当一个逻辑操作跨越多个 SDK 调用时，您可以为每次调用提供自己的密钥（TypeScript 中为 idempotencyKey，Go 中为 option.WithIdempotencyKey，Python 中为 idempotency_key）。要检测重放，可通过各 SDK 的传输元数据访问器读取 Idempotency-Replay 响应头：TypeScript 中为 .withResponse()，Go 中为 option.WithResponseInto，Python 中为 with_raw_response。