# 幂等

幂等键的位置，格式与服务端语义，同一个键只评测一次，只计费一次。

来源：https://open.shengzhiai.com/sdk/v2/api/idempotency/

## 幂等键

| 接口 | 幂等键的位置 |
|---|---|
| 原生整段评测，兼容整段评测，语音合成 | 请求头 `Idempotency-Key`，也认 `X-Idempotency-Key` |
| 原生实时评测 | 开始帧字段 `idempotencyKey`，开始帧没带时取握手 query 的 `idempotencyKey` |
| 兼容实时评测 | 参数帧字段 `idempotencyKey`，参数帧没带时取握手 query 的 `idempotencyKey` |

键长 1 到 200 个可见 ASCII 字符。SDK 每个逻辑请求自动生成 32 位小写十六进制随机串，调用方也可以指定，例如业务单号。重试与断线重连复用同一个键。不带键时行为与 `1.x` 版本完全一致。

## 服务端语义

| 情形 | 服务端行为 |
|---|---|
| 首次出现的键 | 正常评测与计费，结果保存 24 小时 |
| 同一个键，同一个请求，首次已成功 | 不再评测，不再计费，原样返回首次结果，REST 响应头带 `Idempotency-Replayed: true`，实时评测结果帧带 `"replayed": true` |
| 同一个键，同一个请求，首次仍在处理 | 最多等 30 秒，等到即重放首次结果，等不到回 HTTP 409，错误码 40901，响应头 `Retry-After: 2` |
| 同一个键，不同的请求 | 回 HTTP 409，错误码 40903，不评测 |
| 首次请求失败 | 释放这个键，用同一个键重试会重新评测 |

请求是否相同按请求指纹判断：整段评测为 config 加音频加图片，兼容接口为 coreType 加全部文本表单字段加音频，语音合成为请求体，实时评测为评测参数加这一轮的音频。键按租户隔离，签名鉴权按 appKey，token 鉴权按用户，不同租户用同一个键互不影响。服务端记录处理中状态最长 15 分钟，进程异常退出后键在 15 分钟内自动释放。

## 重试时序

1. 应用代码 到 SDK：evaluate(audio, config)
2. SDK 到 开放平台：POST /api/v1/evaluate，键 7f3a…
3. 开放平台 到 SDK：读取超时，未送达
4. 说明：第 1 次重试前等待 200 ms，乘以 0.7 到 1.3 的随机系数
5. SDK 到 开放平台：POST /api/v1/evaluate，键 7f3a…
6. 说明：同一个键的首次请求已完成，平台不再评测，不再计费
7. 开放平台 到 SDK：200  Idempotency-Replayed: true
8. SDK 到 应用代码：评测结果，重放标记与尝试次数 2

SDK 侧的幂等键生成，指定与关闭方式见[重试与幂等](https://open.shengzhiai.com/sdk/v2/guides/retries/)。