语音通知接口超时与重试机制设计：保障告警不丢失

为什么告警场景要设计超时与重试

语音通知常用于系统告警、风控提醒、紧急通知等不能丢失的场景。网络抖动、接口短暂不可用都可能让一次提交失败，如果业务方不做超时控制与重试，这条关键通知就会被静默丢弃。设计一套可靠的提交与重试机制，是保障告警不丢失的关键一环。

接口提交阶段的超时

调用发送接口 https://api.ihuyi.com/voice/vm 时，应给 HTTP 客户端设置合理的连接与读取超时。建议连接超时控制在数秒内，读取超时根据响应耗时设置，避免线程长时间挂起。接口返回 JSON，成功时为 {"code":2,"msg":"提交成功"}。

import requests
try:
    r = requests.post("https://api.ihuyi.com/voice/vm",
        data={"account":"ID","password":"KEY","mobile":"13800138000",
              "content":"系统告警，请尽快处理"}, timeout=(3,10))
    if r.json().get("code") != 2:
        raise RuntimeError(r.text)
except requests.RequestException:
    enqueue_retry(...)

重试策略

提交失败后不要无限重试，建议采用指数退避：

1. 首次失败后等待较短时间重试，例如 2 秒、4 秒、8 秒，逐步拉长间隔。
2. 设置最大重试次数，例如 3 到 5 次，超过后转入人工告警通道兜底。
3. 对返回明确业务错误（如手机号格式错误、余额不足）的请求不应重试，避免无意义刷屏。

与平台补呼配合

提交成功只代表任务被受理，用户未接听时，平台支持失败自动补呼：振铃 60 秒未接，可按自定义次数与间隔再次外呼。业务侧应把"提交失败重试"与"平台接听补呼"区分开，前者解决提交阶段的网络问题，后者解决用户未接的问题。最终通话结果通过回调回传，配合通话时长与接听时间对账。详见 https://www.ihuyi.com/doc/voice/vm/api 。