幂等与重试
恢复已完成的决策，避免重复推理和重复扣费。
为每次逻辑操作提交幂等键
客户端必须自行提供 Idempotency-Key，SDK 0.3.0 不会自动生成。可以使用 UUID。键长度为 1–128 个字符，首位必须是字母或数字，之后允许字母、数字、点、下划线、冒号和连字符。
发送前将键与业务操作一起保存。响应丢失或连接超时后复用原键；生成新键意味着新的可计费操作。
const operationKey = crypto.randomUUID();
const result = await client.evaluate(request, {
maxRetries: 0,
timeoutMs: 30_000,
headers: { 'Idempotency-Key': operationKey },
});这里的 request 与 client 对应快速开始中的请求对象和已配置客户端。恢复操作时重建相同请求，并复用 operationKey。
作用范围与比较规则
幂等键的作用范围是 账户，同一账户的各 API 密钥和会话 Playground 共享该范围。不同账户拥有独立命名空间。认证仍然有效：已撤销的 API 密钥不能用于重放。
平台比较验证后的完整规范化请求，包括全部扩展字段。对象键顺序和格式化空白不影响哈希；数组顺序、问题内容、状态值、null 与省略字段的区别，以及评分档位顺序都会影响。省略模型时，在哈希前补入部署默认值，未配置则为 jev-latest；显式别名或版本不变。恢复时应保持同一实际请求模型。不同规范化正文返回 409 idempotency_conflict。
因此，只有排版空白不同的请求仍属于同一逻辑操作。十进制标识会保留高精度差异：9007199254740993 不能与 9007199254740992 共用哈希，1e-400 也不能等同于零；等价数字写法会规范化到同一值，重复键会被拒绝。原生成功保真比较的是网关响应与该次调用实际收到的上游响应，而不是两个独立模型请求的结果。用户原始幂等键不会转发到共享的上游运营者账户。
各状态的处理方式
| 已有操作状态 | 相同键与请求体的响应 | 客户端处理 |
|---|---|---|
| 没有保留中的操作 | 可以开始新推理并预扣积分。 | 保存此键，直到结果明确。 |
| 处理中 | 409 request_in_progress，Retry-After: 2。 | 等待后用相同键和请求体重试。 |
| 成功 | 返回原状态、响应文本及允许的响应头，设置 X-Idempotency-Replayed: true，不再次推理或扣费。 | 使用恢复的答案。 |
| 已失败并退款 | 409 idempotency_failed。 | 仅在决定重新尝试时使用新键。 |
| 请求体不同 | 409 idempotency_conflict。 | 恢复原始请求，或为不同操作使用新键。 |
| 重放记录缺少响应数据 | 410 idempotency_expired。 | 核对原操作状态后再决定是否新建请求。 |
新格式成功重放通过 X-Request-Id 返回原平台 ID，同时保留原上游跟踪 ID，设置 X-Idempotency-Replayed: true 和 X-System-One-Credits: 0。缓存正文保持不变，不新增 replayed、billing 或 request_id；正文已有的同名字段属于上游，不用于平台记账。重放尝试仍受账户限流约束。
缓存升级与响应模式
新缓存把响应文本、状态和允许的响应头存入现有 response_json 列中的版本化结构。该结构属于内部存储，不是公开响应正文。typesafe-native 保留原 TypeSafe 文本；openrouter-adapted 重放已保存的适配响应，不承诺 TypeSafe 原生字节保真。
升级前未带版本的记录无法恢复原始上游文本。它们以 X-System-One-Response-Mode: legacy-cache 返回，不重新推理或扣费。旧平台添加的 billing、request_id 和 replayed 正文字段会被移除；历史上合成的 rounding 和 warnings 无法可靠地区分来源，可能仍会保留。这些缓存仍按原 24 小时窗口过期，无需迁移数据库结构、账户或账本。
保留时间与异常
已完成操作的幂等键和响应缓存从请求创建起保留 24 小时。到期后，相同键可以发起新操作，不提供永久去重保证。清理任务也会移除过期重放数据。不提供幂等键时不会缓存答案，重复发送属于新的推理。
普通推理失败会先返还预扣积分，再返回错误。进程中断可能留下处理中记录。超过 15 分钟的预扣可由每 15 分钟运行一次的清理任务对账，因此恢复并非立即完成。状态不明确期间，请保留原键和请求 ID。
503 request_reconciliation_pending 表示即时积分对账未完成。因扣费状态尚未确定，X-System-One-Credits 会省略；缺失不等于零。不要假定新尝试免费，也不要盲目换新键重试。保留 X-Request-Id 并检查用量；对账长时间未完成时，请联系部署运营者排查。
SDK 重试
SDK 默认重试策略可以重试网络错误和部分 HTTP 错误，但不会自动处理平台的各种 409 状态。示例设置 maxRetries: 0，由应用根据上表处理。启用 SDK 重试也不会生成幂等键，仍须显式提交并保存。Worker 本身不重试上游推理。
原始 HTTP 分类响应头与 SDK 错误类不同。项目 SDK 0.3.0 的 APIError 暴露状态、请求 ID 和重试延迟，不暴露完整正文或分类响应头。需要区分各种 409 时，用 Fetch 从 X-System-One-Error-Code 读取。除文档列出的安全替换外，上游错误保留原状态与有效 JSON；应检查 Error-Source，不能把所有 401 都当成平台登录过期。官方客户端的独立重试配置也需要显式提供并保存幂等键。