企微 API 接口返回 invalid token 错误怎么排查？

遇到企微 API 接口返回 invalid token 错误，最优先的处理方向是检查 access_token 的获取逻辑与缓存机制，确认是否因 token 过期或频繁刷新触发限流，该方案适用于大多数自建应用调用场景。

先说结论：invalid token 通常意味着 access_token 失效或获取方式不符合规范，需优先排查缓存时效与 IP 白名单。

先确认：检查返回的具体错误码是 40001 还是 42001，区分是凭证错误还是频繁获取。
先处理：核对服务端 IP 是否加入白名单，并清理本地过期的 token 缓存。
再验证：使用新获取的 token 调用简单接口，确认返回包中 errcode 为 0。

错误码与报文分析

企微 access_token 有效期通常为 7200 秒（2 小时）。出现 invalid token 主要有三种情况：token 自然过期未刷新、获取频率过高触发限流、调用接口服务器 IP 不在白名单内。

查看 API 返回的 JSON 包，典型错误响应如下：

{
    "errcode": 40001,
    "errmsg": "invalid credential value, invalid access_token"
}

若 errcode 为 40001 表示凭证失效，42001 表示 access_token 过期。

排查与解决步骤

1. 核对 IP 白名单：登录企业微信管理后台，进入应用管理页面，确认调用接口的服务器出口 IP 已添加至可信 IP 列表。

2. 检查缓存逻辑：确认代码中是否有对 access_token 进行缓存，避免每次业务请求都重新调用 gettoken 接口。

3. 强制刷新：在确认白名单无误后，手动清除缓存中的旧 token，重新请求获取新的 access_token 并更新缓存。

缓存实现参考

建议使用 Redis 集中管理 token，避免多实例缓存不一致。以下是一个简单的 Python 缓存逻辑示例：

import redis
import requests

r = redis.Redis(host='localhost', port=6379)
CACHE_KEY = "wecom_access_token"

def get_token():
    token = r.get(CACHE_KEY)
    if token:
        return token.decode()
    
    # 获取新 token
    url = "https://qyapi.weixin.qq.com/cgi-bin/gettoken"
    params = {"corpid": CORPID, "corpsecret": CORPSECRET}
    resp = requests.get(url, params=params).json()
    
    if resp.get("errcode") == 0:
        new_token = resp.get("access_token")
        # 设置过期时间略小于 7200 秒，预留缓冲
        r.setex(CACHE_KEY, 7000, new_token)
        return new_token
    else:
        raise Exception("Get token failed")

验证与测试

使用新获取的 token 调用一个轻量级接口，例如读取部门列表。

curl "https://qyapi.weixin.qq.com/cgi-bin/user/list?access_token=YOUR_ACCESS_TOKEN&department_id=1"

若返回包中 errcode 为 0 且包含具体数据，说明 token 已恢复有效。

服务端缓存清理实操（Redis）：

# 查看当前缓存的 token
redis-cli get wecom_access_token
# 清除旧 token 强制刷新
redis-cli del wecom_access_token

实施注意事项

1. 频率限制：不要在每次业务调用时都去请求新的 token，这会触发频率限制导致后续 token 全部失效。

2. 凭证安全：corpId 和 secret 不要硬编码在代码库中，建议通过环境变量或配置中心管理。注意 curl 命令中的 secret 可能会留存于历史命令记录，生产环境建议使用环境变量传递。

3. 多实例一致性：如果服务部署了多台服务器，需确保 token 缓存共享（如使用 Redis），避免部分实例持有旧 token。

参考来源

企业微信开发者文档 - 访问令牌
URL: https://work.weixin.qq.com/api/doc