结论先行
幂等、重试和对账不是三个孤立功能，而是一条故障处理链：唯一标识帮助识别同一业务意图，幂等语义决定重复提交是否安全，有限重试处理短暂故障，对账确认请求与最终账务结果是否一致，人工升级处理系统仍无法确定的状态。
最危险的误区是“超时就是失败，所以再发一次”。请求在服务端完成后，响应仍可能在网络中丢失。此时调用方看到的是状态不明，而不是已确认失败。若接口没有明确的幂等或查询语义，自动重试可能产生重复会话、重复转账或重复记账。
先区分五个概念
| 概念 | 准确定义 | 它不能单独保证什么 |
|---|---|---|
| 唯一标识 | 用稳定值关联同一请求、交易、局或投注 | 有唯一字段不等于服务端一定去重 |
| 幂等 | 对同一业务意图重复执行，预期最终效果与执行一次相同 | 不要求每次响应文本完全相同，也不等于请求永不失败 |
| 重试 | 在限定条件、次数和时间预算内再次尝试 | 不能把永久错误变成成功，也不能替代状态查询 |
| 对账 | 比较请求意图、业务结果、交易或局记录和账务结果 | 不能自动决定所有差异如何补偿 |
| 人工升级 | 当自动系统不能安全下结论时，由授权角色调查和决策 | 不是用人工猜测覆盖缺失日志或协议 |
HTTP 方法本身也不能替业务协议作决定。RFC 9110 把 PUT、DELETE 和安全方法定义为幂等，并明确客户端不应自动重试非幂等请求，除非已知其实际语义是幂等的，或能够判断原请求未被执行。公开 API 参考中的平台调用均以 POST 展示，因此不能仅凭 HTTP 方法推断某次业务操作可安全重试。
1. 唯一标识：区分追踪 ID 与业务交易 ID
可靠性设计通常至少需要两类标识：
- 请求追踪标识：把一次调用与日志、响应和排障记录关联；
- 业务交易标识：表达一次业务意图，并关联转账、账变、局或投注记录。
公开 API 参考展示了 reqTraceId，并在部分交易流程中展示 merchantTransactionId、transactionId、roundId 和 betId 等字段。其中 merchantTransactionId 被描述为可用于对账的商户交易唯一标识。
这些字段证明公开模型提供了追踪和关联线索，但不能据此补写以下未确认语义：服务端是否对所有接口去重、去重作用域和保留期限、同一标识但参数不同时如何处理、重放后返回原结果还是新结果。上述内容必须由正式接口协议和实际测试确认。
IETF 的 draft-ietf-httpapi-idempotency-key-header-07 曾提出 Idempotency-Key HTTP 标头设计，但截至 2026-08-09 已过期归档，未成为 RFC。项目只能把它作为历史设计参考，不能称为当前标准，不能把该草案写成 AG 当前协议，也不能默认 AG 支持这个标头。
2. 重试：只对合适的错误和操作执行有限尝试
自动重试应同时满足两个条件：错误被判断为短暂故障，并且重复操作在当前协议下是安全的。建议在项目协议中建立明确分类：
| 场景 | 默认处理原则 | 自动重试前提 |
|---|---|---|
| 只读查询或列表 | 可考虑有限重试 | 协议确认没有副作用，且错误属于短暂故障 |
| 会话创建 | 不因超时直接重建 | 有明确幂等或按原标识查询现有会话的语义 |
| 钱包或转账变更 | 默认先查状态或对账 | 业务交易标识、幂等作用域和重复结果均已确认 |
| 回调处理 | 消费方应识别重复事件 | 双方确认用于去重的稳定事件或交易标识 |
| 参数、权限或签名错误 | 不自动重试相同请求 | 修复参数、权限、时钟或凭据后作为新决策处理 |
| 超时或断连 | 标记为状态不明 | 先按原标识查询；只有安全语义成立时才有限重试 |
重试必须有边界，包括单次超时、最大尝试次数、总时间预算和停止条件。本文不规定具体数字，因为参数应根据接口语义、上游限制、业务风险和双方协议确定。
3. 指数退避与 jitter：避免所有客户端同时再次施压
当短暂错误确实允许重试时，可以采用带上限的指数退避，并加入随机抖动（jitter）。概念上，第 n 次等待会随尝试次数增加，并被最大等待上限截断；jitter 再把大量客户端从同一重试时刻分散开。
AWS 和 Google 的官方资料都强调退避与 jitter 的价值。Google 同时明确，是否重试仍取决于错误是否可重试以及操作是否幂等。退避算法不能让一个非幂等写操作自动变安全，也不能替代总重试预算。
应避免以下反模式：
- 无上限或立即循环重试；
- 对所有 HTTP 或业务错误使用同一策略；
- 网关、SDK、服务和任务队列在多个层级各自重试，导致次数相乘；
- 每次重试生成新的业务交易标识，使服务端无法识别同一意图；
- 在重试日志中记录密钥、完整凭据或不必要的敏感数据；
- 第一次自动重试失败后继续无限自动重试。RFC 9110 对自动重试也要求谨慎，尤其不应把连续失败变成无界重放。
4. 状态不明：不要把未知状态改名为失败
当请求已经发出但没有取得完整业务结果时，建议进入独立的 UNKNOWN 状态。一个不绑定 AG 具体协议的通用状态流可以表达为：
NEW -> SENT -> CONFIRMED_SUCCESS
-> CONFIRMED_FAILURE
-> UNKNOWN -> QUERY_OR_RECONCILE -> CONFIRMED_SUCCESS
-> CONFIRMED_FAILURE
-> MANUAL_REVIEW处于 UNKNOWN 时，优先使用原请求或业务交易标识查询既有结果、交易记录或账变。若协议没有权威查询能力，系统应停止可能产生重复效果的自动动作，保留上下文并进入人工处理，而不是自行假设失败。
状态名称、查询接口和终态仍应以双方协议为准。上图只是设计方法，不表示 AG 当前实现了这些精确状态。
5. 对账：用多个证据确认最终业务效果
对账不是简单比较两个余额。对于涉及钱包、投注或派奖的流程，建议至少关联：
- 原始业务意图和请求追踪标识；
- 商户或平台业务交易标识；
- 对端交易、局、投注等标识；
- 金额、币种、方向和时间解释；
- API 业务结果与后续记录；
- 钱包账变、当前余额和最终处理状态。
对账结果可以分为已一致、已确认失败、重复、金额或币种不一致、记录缺失和状态不明。任何差异都需要预先定义责任人、调查证据、补偿权限和关闭条件。不要用再次发送原始资金请求来代替对账。
对账频率、数据保留和允许差异应由业务风险、交易量、钱包模式与合同共同决定，本文不为 AG 声明固定周期或阈值。
6. 什么时候必须人工升级
满足以下任一条件时，应停止自动处理并转入有审计记录的人工升级：
- 已用尽有限重试预算，业务状态仍无法确认；
- 相同业务标识对应不同金额、币种、账号或其他关键参数；
- 请求结果、交易记录和钱包账变互相矛盾；
- 找不到协议规定的权威记录，或关键日志不完整；
- 涉及疑似重复扣款、重复派奖、未授权访问或安全事件；
- 自动补偿可能扩大资金、合规或客户影响。
人工处理记录至少应包括原始标识、时间线、已执行动作、证据、风险判断、批准人和最终关闭结果。敏感凭据和密钥不应进入工单正文。
一页实施检查表
- 为请求追踪与业务交易分别定义稳定标识；
- 为每个有副作用的操作写明幂等作用域、冲突和重复响应语义；
- 将短暂错误、永久错误和状态不明分开；
- 只对已确认安全的操作执行有限重试；
- 为允许重试的路径设置超时、总预算、指数退避上限和 jitter；
- 防止多个系统层级叠加重试；
- 为状态不明提供按原标识查询或对账路径；
- 用交易、局、金额、币种和账变等证据完成对账；
- 定义自动处理停止条件与人工升级责任；
- 用超时、响应丢失、重复提交和记录差异进行 staging 验收。
当前可用于项目评估的范围
- 公开 API 参考为请求、部分业务交易、局和投注展示了唯一标识字段；
- 接口说明要求结合响应体中的业务结果判断调用结果，而不只看 HTTP 状态；
- 钱包和交易、局、投注等记录查询可用于设计追踪与对账；
- 现有页面分别介绍单钱包和转账钱包，但具体可靠性方案应随钱包模式和正式协议确定。
使用这些信息时需要注意什么
- 不声明 AG 的所有 POST 接口都幂等，也不声明当前支持
Idempotency-Key标头； - 不发明 AG 的去重范围、标识保留期、冲突响应、重试次数、退避参数或对账周期；
- 不新增查询、补偿、状态或生产端点；
- 不承诺零重复、零丢失、绝对一致、绝对安全、固定性能或 SLA；
- 不把公开 API 示例视为任何具体项目的 production 协议、运行时行为或准入证明。
常见问题
POST 请求失败后可以自动重试吗？
不能仅凭“请求失败”或 POST 方法决定。要先判断错误是否短暂、原请求是否可能已经生效，以及正式协议是否提供幂等或按原标识查询的语义。否则应进入状态不明和对账流程。
超时是否代表交易失败？
不代表。超时只表示调用方没有按时得到完整结果，服务端可能尚未处理、处理中、已成功或已失败。应使用原业务标识查询或对账。
有唯一交易 ID 是否就已经实现幂等？
没有。唯一 ID 是识别同一业务意图的重要基础，但还要确认服务端如何保存和比较它、作用域和期限是什么、参数冲突如何处理，以及重复请求返回什么结果。
重试时应该生成新的请求 ID 吗？
取决于协议如何区分“同一业务意图”和“单次传输尝试”。业务交易标识通常需要保持稳定，追踪标识是否复用或派生必须由双方协议明确，不能从本文或字段名称自行推断。
延伸阅读与下一步
- 相关页面：公开 API 参考、Slots API、集成流程
- 当前相关内容：两种钱包模式如何选择
- 继续阅读：从 staging 到 production 的验收清单、Slots API 术语表
如需为具体接入设计可靠性方案，可通过“联系我们”提供钱包模式、调用方向、关键业务操作和现有对账能力；AG 再根据正式协议确认标识、状态查询、重试边界和升级责任，不预先承诺生产行为。
参考资料与适用说明
相关字段和范围可参考公开 API 参考、Slots API与集成流程。具体实施仍应对照双方确认的接口协议和环境行为。
通用语义与可靠性方法参考：
- IETF / RFC Editor：RFC 9110：HTTP Semantics，用于幂等方法和自动重试边界；
- IETF Datatracker：The Idempotency-Key HTTP Header Field, draft-ietf-httpapi-idempotency-key-header-07，截至 2026-08-09 已过期归档，未成为 RFC，仅作历史设计参考；
- AWS Builders’ Library：Making retries safe with idempotent APIs与Timeouts, retries and backoff with jitter；
- Google Cloud：Retry strategy，用于错误可重试性、操作幂等性、指数退避和 jitter 的一般原则。
这些来源解释通用设计，不确认 AG 已采用某个厂商的算法、参数或标头。协议语义与示例字段仍需由 API、钱包、SRE、安全和对账负责人按项目复核。
需要把指南转成项目方案？
文章用于帮助团队梳理采购和接入问题，不替代技术、合同、认证或当地法律确认。