第三方接口超时后该不该重试？查单、幂等与补偿设计指南

订单发到物流系统后接口超时，平台不知道发货申请是否成功。如果立即重发，可能生成两张运单；如果不处理，订单又可能一直卡住。系统集成要解决的正是这种结果不确定的中间状态。

一、把业务失败与通信失败分开

库存不足、参数错误和网络超时不能采用同一种处理。前两者需要调整业务或数据，超时则可能是服务端已处理而响应丢失，盲目重发只会增加不确定性。

接口适配层按正式文档区分明确成功、明确失败和结果未知，保留对方请求编号。不要仅凭HTTP状态码或一句返回消息就宣布整笔业务完成，业务结果还需要相应校验。

二、一个业务动作保持一个编号

用户重复点击或后台任务重试时，如果每次都生成新的外部订单号，第三方会把它们当成不同请求。即使对方支持幂等，也无法识别这些操作实际上来自同一次下单。

在本地先生成并保存稳定业务编号，后续查询和重试复用该编号。核对合作方幂等键的作用范围和保留时间，本地仍保存处理记录，不能假定所有外部接口天然具备相同保证。

三、结果未知时优先核对原申请

物流、支付或其他执行系统可能提供按业务编号查询的接口，这通常比创建新申请更能减少歧义。但查不到一次也不必然代表不存在，外部系统可能有短暂处理延迟。

定义查询间隔、观察上限和人工介入条件，始终保留原申请信息。没有查询能力的接口应提前明确对账与支持渠道，高影响动作不要在未知状态下由用户反复点击创建。

四、重试要有次数与时间预算

每个服务都立即重试三次，经过多层调用后可能放大为大量请求，让原本短暂的故障持续更久。用户等待时间也会随着多层超时叠加，影响其他正常操作。

为完整业务链设置总超时与重试预算，对暂时性故障采用受控间隔，避免所有客户端同刻重试。微软Retry模式强调结合幂等性与故障类型判断适用性，并非任何失败都值得自动重试。（参考：Microsoft Learn：重试模式）

五、本地状态和发送记录一起追踪

数据库已经记为待发货，却没有成功保存发送任务，后台就可能永远不知道这张订单需要补发。相反，外部执行成功而本地未记账，也会使操作被再次执行。

把待发送事实与本地业务变更可靠关联，执行者记录尝试和确认结果。具体采用事务发件箱或其他机制取决于现有架构，但必须能从业务单追到外部动作，避免只依赖易丢失的内存通知。

六、补偿不是把数据库恢复成昨天

外部动作已经执行后，本地回滚不能撤销真实发货或付款。撤销本身也可能失败，还可能需要客户同意，所以补偿流程应当对应业务可接受的恢复方式。

对每一步注明可撤销、可重试或需人工处理，记录补偿进度和失败原因。仓储出库、消息发送等动作不可一概而论；异常列表需要明确责任人，不能把待人工处理当成已修复。

七、验收要主动制造重复和超时

合作方演示环境响应稳定，最关键的错误路径往往不会自然出现。仅发送一次成功请求，无法验证系统对未知结果、重复回调和重试中断的处理。

模拟请求到达后响应丢失、回调先于响应、重复消息和查询延迟。核验一笔业务最终只产生一次有效结果，所有异常可追踪、可对账，并确认人工重处理不会绕开同一套保护。

上线前检查清单

1. 01　业务失败与结果未知分开
2. 02　重试复用稳定业务编号
3. 03　支持按原申请查询
4. 04　重试次数总时长有上限
5. 05　本地变更关联发送记录
6. 06　补偿符合实际业务规则
7. 07　人工重处理仍有幂等保护
8. 08　重复与超时场景经过演练

武汉米能科技有限公司以“米能软件”对外提供APP、微信小程序、企业管理系统与AI应用定制开发。项目先确认业务边界、资料基础与验收样例，再确定实施范围和技术路线。具体功能、交付周期、数据权限及维护责任以双方确认的方案和合同为准。