企业微信 API 接口对接踩坑全记录：消息丢失、鉴权失败与高并发应对方案

直接讲三个我在企微对接里真踩过的坑——消息丢失、鉴权失败、高并发打挂服务，以及最后是怎么修好的。每个坑都带排查思路和落地代码。

坑一：消息"偶尔丢失"，其实是重复推送被当新消息

现象：客户说发了三条消息，系统只处理了一条。

排查：翻回调日志发现，同一条原材料被打了好几次。原因是我一开始没做幂等——企微回调是"至少一次"投递，网络抖动或我返回慢，它就会重推。

修复：用X-Eyun-Delivery头做去重，同一个投递 id 只处理一次：

delivery = request.headers.get("X-Eyun-Delivery") if not redis.setnx(f"cb:{delivery}", 1, ex=86400): return "ok"

顺带把"5 秒内返回"这条铁律落实——处理放到队列，接口先返回 ok。返回慢是重复推送的主因。

坑二：鉴权失败，两套 code 体系搞混了

现象：接口返回code: "40001"（字符串），一度以为封套解析错了。

排查：企微 API 的响应 code 有两套含义。网关和鉴权层的错误，code 是字符串；业务层的成功是数字 0、失败是 -1，具体错误码在 message 里。

// 成功 {"code": 0, "data": {...}, "message": ""} // 业务失败 {"code": -1, "data": null, "message": "具体错误"} // 鉴权失败 {"code": "401", "message": "token invalid"}

修复：判断成功别写if code == 0就完事，要区分类型：

def is_ok(resp): return resp["code"] == 0 # 数字 0 才算业务成功

另外两个高频原因：Token 过期（有效期 7200 秒，要提前刷新）、个人号和企微号的凭证混用（两条产品线凭证不通用）。

坑三：高并发下接口被限流打挂

现象：做活动期间推送量大，接口返回 -301002 一片一片，业务消息积压。

排查：-301002 是企微的限流码。当时没有前置限流，全靠平台返回后再退避，等于把压力全打出去。

修复三步：

1. 前置令牌桶：按接口路径分别限速，别共用一个桶

2. 指数退避：被拒后按 2^n 秒重试，封顶 32 秒

3. 队列削峰：业务事件先入队，Worker 按节奏消费

def call_with_retry(module, action, payload, retries=4): for i in range(retries): resp = request_call(module, action, payload) if resp["code"] == -1 and "301002" in str(resp["message"]): time.sleep(min(2 ** i, 32)) continue return resp queue.push({"module": module, "action": action, "payload": payload})

三个坑的共同教训

回头看，这三个问题的根子是同一类：

企微对接要稳，靠的不是单点技巧，而是"幂等、类型清晰、限流前置"这三条原则贯穿始终。

接口用的是 Eyun 平台的企业微信 API，路径统一是/wx-api/api/<模块>/<动作>，鉴权Bearer eyk_xxxx，凭证在官网开通实例时拿到。开发文档里把错误码和封套结构写清楚了，对着查比瞎试快得多。