接口超时排查决策树：从读超时配置到重试纪律
实名认证类接口四种超时症状的本质区分、四层排查决策树、读超时为何要给到 30 秒、重试三条纪律(一次/退避/带对账)与一个日均 8000 次客户的真实处理案例。
对接实名认证类接口的工单里，"超时"从来不是单一问题——它是网络、链路、参数、计费四类问题的混合症状。这篇把超时的排查顺序整理成决策树，从"请求发出去就没回来"到"上游超时该不该重试"，每一层给判断依据和处理动作。
先分清：你遇到的是哪一种"超时"
同一个词，至少对应四种不同情况，处理方式完全不同：
第 1 和第 3 的区别最要命：客户端断开连接不代表服务端停止处理——你的重试打过去，两次核验都完成、两次都计费。所有"超时重试"的前提是先确认请求是否已到达上游，这也是为什么对接文档里都强调幂等设计。
排查决策树（按顺序问）
1. 所有请求都超时，还是部分？
├─ 全部 → 检查网络出口/防火墙/IP 白名单（先排除自己） └─ 部分 → 2. 部分超时集中在特定时间段吗？ ├─ 是（如整点/高峰）→ 上游限流或高峰拥堵，错峰+降并发 └─ 否 → 3. 超时的请求有共同特征吗？ ├─ 同参数反复超时 → 检查参数（生僻字、超长字段触发上游慢查询） └─ 随机分布 → 上游抖动，看第 4 步 4. 服务商返回超时错误码了吗？ ├─ 有（如 1105/1110 类）→ 上游明确超时，可重试一次 └─ 无（客户端自己断的）→ 先查这笔到底成没成（对账），再谈重试
读超时该设多少
核验类接口的链路是：你的服务 → 服务商网关 → 服务商后端 → 权威数据源。四跳里任何一跳慢都表现为你的等待时间变长。行业合理的读超时是 30 秒——低于这个值（常见 5 秒、10 秒）会把"上游慢"误判成"请求失败"，重试风暴就是这么来的。连接超时可以短（3-5 秒），读超时要给足。
import httpx
with httpx.Client(timeout=httpx.Timeout(connect=5.0, read=30.0, write=10.0)) as client: resp = client.post(url, data=payload)
重试的纪律：一次、退避、带对账
确认是"上游超时"类可重试错误后，纪律只有三条：
一个真实场景的完整处理
某客户日均 8000 次核验，某天下午超时率从 0.3% 跳到 12%。按决策树走：
处理：错峰调度非实时业务（批量对账类挪到凌晨）、实时业务读超时提到 30 秒、超时请求全部落单号待对账。当天超时率回落到 2% 以内，次月账单核对退回 41 笔争议扣费。
如果当时直接上重试，高峰期的超时会被放大成三倍请求量，触发更严重的限流——超时处理的第一原则永远是"先搞清楚，再动手"。