对接企微 API 最烦的就是调不通——接口返回个 code文档里找不到对应含义只能瞎猜。我把过去半年踩过的所有错误码整理成一张速查表按出现频率排序再给一个统一处理的封装复制到你项目里当基础设施用。先搞清楚企微有两套code 体系返回结构统一是{code, data, message, detail, time}但 code 可能是数字也可能是字符串类型code 示例含义排查方向数字 code0、-1业务层返回0 成功-1 业务失败看 message 字段字符串 code40001、42001、-301002网关层返回token、限流、签名、网络等基础设施问题最容易踩的坑只做了if code 0判断没管字符串 code。字符串 code 出现时 code 本身不是 0也不是 -1会被漏掉。高频错误码速查表40001 / 42001 — Token 相关最常见code含义排查步骤40001Token 过期或无效1. 看 token 获取时间是否超 7200 秒2. 检查Authorization: Bearer eyk_xxx是否拼对3. token 有没有被手动重置过42001Token 刷新频率超限token 还没过期就又去拉了API 检测到并发刷新直接拒。缓存 token到期前 300 秒再刷我上周线上遇到过一次——部署新代码时改了 token 刷新策略改成每次请求都先拉 token结果 10 分钟内连续触发了 42001整条链路挂了。45009 / -301002 — 限流相关第二常见code含义排查步骤45009企微官方接口限流调 sendMessage、addExternalContact 等高频接口时超过官方配额。解决方案加延时队列、批量接口代替单条-301002平台侧限流token 刷新、Webhook 回调等有独立限流。token 缓存好能解决 90%区分两者45009是企微原生接口返回的-301002是平台网关层拦截的。-1 — 业务失败看 message 字段code: -1时必须读 message 字段真正原因在里面resp api.post(/wx-api/api/message/sendText, {...}) if resp[code] -1: print(resp[message]) # ← 真正的错误原因在这里常见 message 内容message原因解决invalid chatIdchatId 传错或类型不对chatId 是 int64必须传 JSON numberinvalid externalUserId外部客户不存在先拉客户列表确认 externalUserIdexternalUserId forbidden不能给这个客户发消息客户已经删除好友了message content too long文本超 4096 字节拆成两段发no permission接口权限没开企微后台检查应用权限签名错误 类code含义排查步骤40002Authorization 头格式错误必须是Authorization: Bearer eyk_xxxBearer 空格 token40003请求签名校验失败Webhook 回调的签名问题用平台 SECRET 做 HMAC-SHA25640004echostr 验证失败echostr 必须纯文本原样返回不能包 JSON不常见但要命的code含义排查步骤40005IP 白名单校验失败你的服务器 IP 没加到企微后台40006接口调用频率超限调/wx-api/api/contact/getSyncList等接口太频繁加缓存40007参数类型错误某个字段传了字符串但要求 number典型就是 int64 字段加了引号统一处理一个出口接住所有码速查表解决查真正让业务代码干净的是统一处理——所有出站请求走同一个出口按 code 类型分流def handle_wecom_response(resp): code resp.get(code) message resp.get(message, ) if code 0: return resp.get(data) # 数字 code: 业务错误 if isinstance(code, int): raise WecomBizError(f业务失败: code{code}, msg{message}) # 字符串 code: 网关错误 if isinstance(code, str): # 高频错误码特殊处理 if code in (40001, 42001): # token 过期自动刷一次再重试 refresh_token() return RETRY if code -301002: raise WecomRateLimitError(平台限流稍后重试) if code 45009: raise WecomRateLimitError(企微官方限流降低调用频率) raise WecomUnknownError(f未知错误: code{code}, resp{resp})业务函数从此只关心成功路径token 刷新、限流退避这些恢复动作全部收在处理层里。业务失败-1注意别进重试队列——参数错了重试一万次还是错快速失败加告警才是对的。最后一条排查经验调接口报错时先看原始响应。很多 HTTP 客户端会把非 2xx 状态码直接抛异常掩盖掉企微返回的code和message。用requests时加个timeout然后手动检查resp.status_code别让它自动抛异常。resp requests.post(url, jsondata, timeout15) # 别直接 resp.json()先看状态码 if resp.status_code ! 200: print(fHTTP {resp.status_code}: {resp.text}) # 原始响应比处理后的有用这张表我贴在 IDE 的 Snippet 里了每次接口报错直接搜 code 就能定位比翻文档快太多。当然速查表只是兜底字段和错误码的权威定义还是以 Eyun 开发文档为准——实例和凭证还没配好的话先回Eyun 官网开通再回来对表。
