OpenAPI 幂等键（Idempotency-Key）使用说明

本文说明 Idempotency-Key 在 OpenAPI POST 接口中的用法与行为约定。

适用范围

OpenAPI 下所有 POST 接口。

请求头必须携带：Idempotency-Key: <string>。

基本规则

同一平台渠道 + 同一接口 + 同一 Idempotency-Key 视为同一次请求。

如果同一个 Idempotency-Key 被重复使用：

请求体 完全一致：返回第一次成功/失败的结果（回放）。

请求体 不一致：返回 ErrOperationIsProcessing（防止语义冲突）。

幂等记录默认保留 7 天，到期后可重新使用同一 key。

如对应接口请求头header未传入Idempotency-Key参数，则接口返回414错误码以及对应的错误信息

幂等行为说明

首次请求：进入处理流程，结果写入幂等表。

重复请求：

若上次处理 进行中：返回 ErrOperationIsProcessing。

若上次处理成功：直接返回上次的成功响应（回放）。

若上次处理失败：返回上次的错误码。

示例

请求

行为

第一次请求：正常处理。

失败后重试（相同 key + 相同 body）：直接返回上次失败的错误码。

成功后重试（相同 key + 相同 body）：直接返回上次成功的响应。

常见问题

Q: 重复请求为什么提示处理中？

A: 说明该 Idempotency-Key 对应的请求仍处于处理中（上次还未结束）。

Q: 为什么返回 “请求处理中” 但其实我换了参数？

A: 同一 Idempotency-Key 必须对应同一请求体，参数变化会被拒绝。

业务幂等相关

OpenAPI 幂等键（Idempotency-Key）使用说明

适用范围

基本规则

幂等行为说明

推荐的生成方式

示例

请求

行为

常见问题

Q: 重复请求为什么提示处理中？

Q: 为什么返回 “请求处理中” 但其实我换了参数？

业务幂等相关

OpenAPI 幂等键（Idempotency-Key）使用说明#

适用范围#

基本规则#

幂等行为说明#

推荐的生成方式#

示例#

请求#

行为#

常见问题#

Q: 重复请求为什么提示处理中？#

Q: 为什么返回 “请求处理中” 但其实我换了参数？#

OpenAPI 幂等键（Idempotency-Key）使用说明

适用范围

基本规则

幂等行为说明

推荐的生成方式

示例

请求

行为

常见问题

Q: 重复请求为什么提示处理中？

Q: 为什么返回 “请求处理中” 但其实我换了参数？