REQUEST LIFECYCLE

处理重试,也保留不确定性。

先保存请求内容和业务回执,再根据接口契约决定下一步。

同一个操作,保留同一份请求

只有契约声明支持 Idempotency-Key 的接口才发送该请求头。在第一次提交前生成一次键,并保存原始 body;网络结果未知时保留两者。相同键不能搭配修改后的参数,不要为逃避冲突自动换键。

Idempotency-Key: public-example-operation-0001

原请求 body:保持原字节与业务含义
重试签名:使用本次新 timestamp 和 nonce
业务幂等键:继续使用原键

版本冲突先重新读取,再由调用方决定是否发起新操作;不要自动升级版本后重复原写入。

已经受理,继续查询

收到 operation_id 后保存回执,读取对应资源状态。202 受理回执不代表域名已部署、证书已生效或外部系统已完成处理。模拟记录、ACME staging 证书与真实生产状态分别识别。

未知响应先恢复查询:充值查询原支付订单;退款查询原退款请求和银行卡证据;域名或证书操作查询对应版本及状态。凭证创建/轮换不是可盲重试的幂等接口,Secret Key 也不能从查询接口恢复。

错误与恢复

状态处理方式
400 / 422按契约检查输入和功能支持情况。
401检查当前会话或本次签名,重新认证。
403 / 404确认权限与资源范围,不把 404 当作可重复创建的证据。
409查询原操作、资源版本与幂等参数。
429 / 5xx / 网络中断按接口的重试约定处理,写结果可能未知;先查询回执或资源,不盲目重建业务操作。

不要把缺失信息填成零

未采集的流量不是零流量,未确认的渠道费不是零成本,退款平台成功不等于银行卡已到账。展示 null、unknown、pending 及数据来源时间,让用户知道哪些结果仍待确认。

返回接口目录