先确认现象:超时和5xx要分开看
接到钉钉机器人接入外部API的排查,我一般不会先看代码里的重试次数,而是先让调用方把完整的响应头和异常栈拉出来。因为重试策略只能解决一部分失败,连失败类型都没分清楚,后面的重试逻辑就是空转。
钉钉机器人调用外部API时,首先要区分两类失败:一类是HTTP状态码明确表示服务不可用,比如502、503、504;另一类是请求超时或连接被重置,这类错误往往没有状态码。判断依据建议这样设置:只有请求发出但未收到有效响应时才触发重试,而收到4xx响应(如401鉴权失败、403权限不足)则不应重试,因为重试通常无法解决参数或权限问题,反而会浪费额度并造成日志噪音。
这样分的好处是,重试只处理“请求可能没送达”的情况。4xx 类错误即使重试,参数或权限问题通常依旧存在,只会让日志更乱。我见过不少机器人因为 401 触发重试,结果每次都重新拉 token,导致外部API的鉴权接口被频繁调用,问题反而被放大。
容易被误判的地方:连接重置和鉴权失败
连接重置这类异常容易被当成普通网络错误,但它往往没有状态码,只能靠捕获异常类型来识别。超时错误也要区分是连接超时还是读取超时,连接超时可以重试,读取超时可能意味着请求已经打到服务端,这时重试会带来重复处理风险。
另一种容易误判的情况是鉴权 token 过期。有些外部API的 token 有效期很短,从收到消息到发起调用,可能已经过了几分钟。出现 401 时,正确的做法是先重新获取 token,再决定是否重试,而不是把它和其他4xx一样直接丢弃。
建议的处理顺序:指数退避和随机抖动
如果确认失败属于可重试类型,间隔策略不要用固定时间。
重试间隔建议采用指数退避加随机抖动的方式,而不是固定间隔。例如第一次失败后等待1秒,第二次等待2秒,第三次等待4秒,每次在上限内叠加一个0到500毫秒的随机值。这样做的目的是避免多个钉钉机器人实例在同一时刻集中重试,导致外部API的负载进一步恶化。如果外部API在响应头中提供了Retry-After字段,应优先以该字段为准,并取较大值作为等待时间。
这里要注意,Retry-After 字段在不同接口里的单位不一致,有的返回秒数,有的返回具体时间。实现时先做格式解析,解析失败再退回指数退避,同时用随机值来控制并发。另一个容易被忽略的点是退避上限,如果接口本身已在过载边缘,无限扩大等待时间也不合适,建议根据群聊场景把最长等待时间控制在一个合理范围内。
设置重试上限并考虑异步执行
重试次数必须设置上限,不建议超过5次。原因在于钉钉机器人调用外部API的场景通常对实时性有要求,用户在群聊中等待反馈,过多重试会拉长响应时间,体验明显下降。一个保守的参考值是总重试次数不超过3次,每次间隔递增。如果重试全部失败,机器人应当直接在群内回复一条友好提示,例如“服务暂时不可用,请稍后再试”,同时在日志中记录错误码、请求参数和失败次数,方便排查问题。
这里需要补充一个边界:如果外部API是创建类操作,比如创建工单、发起审批,重试前要确认接口支持幂等键。可以在请求参数里加 client_token,让外部系统根据这个标识判断是否已经处理过。否则网络超时但服务端实际成功时,重试会生成两条记录。
另外,钉钉机器人接收消息后往往有响应时限,同步执行重试很容易把整体响应时间拉长。建议把外部API调用放到异步任务队列里,机器人先回复“处理中”,拿到结果后再补发一条消息。线程池或信号量需要设一个上限,避免同一个机器人短时间内对同一个外部API发起大量并发请求。
验证方法和回滚边界
配置示例可以这样写:重试次数设为3,第一次等待1秒,第二次2秒,第三次4秒,并在每次等待中加上0到500毫秒的随机值。伪代码如下:
const maxRetries = 3;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const resp = await callApi();
if (resp.status >= 200 && resp.status < 300) return resp;
if (resp.status >= 400 && resp.status < 500) break;
} catch (err) {
// 只处理超时、连接重置等可重试异常
}
const wait = Math.min(4000, 1000 * Math.pow(2, attempt - 1) + Math.random() * 500);
await sleep(wait);
}验证时,可以用 nginx 代理临时对某个路径返回 503,确认重试次数和间隔是否符合预期;也可以检查响应头里的 Retry-After 字段能不能被正确识别。观察日志时,重点看每次重试记录里有没有带上尝试次数、剩余等待时间和错误码。第一次失败就要记录聚合信息,而不是等最后失败才打一条日志。
如果发现重试率持续升高,说明外部API可能已经不可用,或网络链路存在故障。这时可以先摘掉部分钉钉机器人实例的流量,或者关闭重试开关,直接返回提示,避免大量请求堆在同步调用上。人工确认外部API恢复后再放量。