全局错误码速查
公众号 / 小程序服务端接口的全局返回码一页查完，按码、errmsg、中文描述或分类过滤，常见码带"先查什么"。
公众号 / 小程序服务端接口共用的全局返回码。输入错误码、errmsg 关键字或中文描述过滤；带"先查什么"的是我们确认过排查顺序的码。
| errcode | 官方说明 | errmsg | 先查什么 |
|---|---|---|---|
-1 | 系统繁忙，此时请开发者稍候再试 | system error | 微信侧临时故障。重试一次；持续出现看开放社区公告。注意换新的 code / 参数重试，不要原样重放。 |
0 | 请求成功 | ok | — |
40001 | 获取 access_token 时 AppSecret 错误，或者 access_token 无效 | invalid credential | 两种情况：换 token 时 secret 错（核对后台是否重置过）；调接口时 token 已被别处刷新（多实例各自取 token 会互相顶掉，要集中缓存）。 |
40002 | 不合法的凭证类型 | invalid grant_type | grant_type 固定：换 access_token 用 client_credential，网页授权 / 登录用 authorization_code。 |
40003 | 不合法的 OpenID | invalid openid | openid 是按 appid 隔离的：公众号的 openid 不能给小程序用，测试号的不能给正式号用。 |
40004 | 不合法的媒体文件类型 | invalid media type | type 只能是 image / voice / video / thumb，且与文件实际格式匹配。 |
40007 | 不合法的媒体文件 id | invalid media_id | 临时素材 3 天过期；media_id 也按 appid 隔离。 |
40008 | 不合法的消息类型 | invalid message type | — |
40013 | 不合法的 AppID | invalid appid | appid 拼错 / 带空白 / 大小写不对 / 用了别的账号的。接口先校验 appid，它不对时别的错误都不会报。 |
40014 | 不合法的 access_token | invalid access_token | 最常见是 token 被别的实例刷新了，或者用了另一个 appid 的 token。集中缓存、只在一处刷新。 |
40015 | 不合法的菜单类型 | invalid button type | 没有 sub_button 的按钮必须有 type。 |
40016 | 不合法的按钮个数 | invalid button size | 一级菜单最多 3 个。 |
40017 | 不合法的按钮类型 | invalid button type | type 拼写，如 click / view / miniprogram。 |
40018 | 不合法的按钮名字长度 | invalid button name size | 一级 16 字节（5 个汉字），二级 60 字节。 |
40019 | 不合法的按钮 KEY 长度 | invalid button key size | key 最多 128 字节。 |
40020 | 不合法的按钮 URL 长度 | invalid button url size | url 最多 1024 字节。 |
40023 | 不合法的子菜单按钮个数 | invalid sub_button size | 每个一级菜单下最多 5 个。 |
40029 | 不合法的 oauth_code / code 无效 | invalid code | code 只能用一次、5 分钟过期，且必须和签发它的 appid 配对。 |
40033 | 不合法的请求字符，不能包含 \uxxxx 格式的字符 | invalid charset | JSON 序列化时关掉 Unicode 转义（如 PHP 的 JSON_UNESCAPED_UNICODE），emoji 直接 UTF-8。 |
40035 | 不合法的参数 | invalid parameter | — |
40037 | 不合法的模板 id | invalid template_id | 模板 id 按账号隔离；从后台"我的模板"复制，不要用文档示例。 |
40038 | 不合法的请求格式 | invalid request format | 要 POST JSON，Content-Type 不影响但 body 必须是合法 JSON。 |
40039 | 不合法的 URL 长度 | invalid url size | — |
40048 | 无效的 url | invalid url | 域名要在后台"业务域名 / JS 接口安全域名"里。 |
40054 | 不合法的子菜单按钮 url | invalid sub button url | 要 http(s):// 开头。 |
40066 | 不合法的 url | invalid url | — |
40125 | 无效的 appsecret | invalid appsecret | secret 与 appid 不是一对，或后台重置过。 |
40163 | oauth_code 已使用 | code been used | 网页授权的 code 被用了第二次：多半是页面刷新或前端重复请求。 |
40164 | 调用接口的 IP 地址不在白名单中 | invalid ip not in whitelist | 后台"IP 白名单"加上服务器出口 IP；用了代理 / NAT 时出口 IP 可能不是机器本身的。 |
41001 | 缺少 access_token 参数 | access_token missing | access_token 放在 URL query 里，不是 body。 |
41002 | 缺少 appid 参数 | appid missing | appid 为空：多半环境变量没读到。 |
41003 | 缺少 refresh_token 参数 | refresh_token missing | — |
41004 | 缺少 secret 参数 | appsecret missing | — |
41005 | 缺少多媒体文件数据 | media data missing | 上传素材要 multipart/form-data，字段名 media。 |
41006 | 缺少 media_id 参数 | media_id missing | — |
41007 | 缺少子菜单数据 | sub_menu data missing | — |
41008 | 缺少 oauth code | missing code | 小程序登录参数名是 js_code，网页授权是 code。 |
41009 | 缺少 openid | openid missing | — |
41030 | page 路径不正确 | invalid page | 不带开头 /；页面必须在已发布版本里（或 check_path=false）。 |
42001 | access_token 超时 | access_token expired | token 有效期 7200 秒，提前刷新（如 7000 秒）并缓存。 |
42002 | refresh_token 超时 | refresh_token expired | 网页授权 refresh_token 有效期 30 天。 |
42003 | oauth_code 超时 | code expired | code 5 分钟过期。 |
42007 | 用户修改微信密码，access_token 和 refresh_token 失效，需要重新授权 | access_token and refresh_token exception | — |
43001 | 需要 GET 请求 | require GET method | — |
43002 | 需要 POST 请求 | require POST method | — |
43003 | 需要 HTTPS 请求 | require https | — |
43004 | 需要接收者关注 | require subscribe | 客服消息 / 模板消息只能发给关注了公众号的用户。 |
43005 | 需要好友关系 | require friend relation | — |
43019 | 需要将接收者从黑名单中移除 | require remove blacklist | — |
43101 | 用户拒绝接受消息 | user refuse to accept the msg | 订阅消息：用户没订阅这条模板，或订阅次数已用完。一次性订阅一次只能发一条。 |
44001 | 多媒体文件为空 | empty media data | — |
44002 | POST 的数据包为空 | empty post data | body 没发出去：检查 Content-Length，或框架把 JSON 放到了 form 里。 |
44003 | 图文消息内容为空 | empty news data | — |
44004 | 文本消息内容为空 | empty content | — |
45001 | 多媒体文件大小超过限制 | media size out of limit | 图片 10M（缩略图 64K）、语音 2M、视频 10M。 |
45002 | 消息内容超过限制 | content size out of limit | 文本客服消息 2048 字节。 |
45003 | 标题字段超过限制 | title size out of limit | — |
45004 | 描述字段超过限制 | description size out of limit | — |
45005 | 链接字段超过限制 | url size out of limit | — |
45006 | 图片链接字段超过限制 | picurl size out of limit | — |
45007 | 语音播放时间超过限制 | playtime out of limit | — |
45008 | 图文消息超过限制 | article size out of limit | — |
45009 | 接口调用超过限制 | reach max api daily quota limit | 每日调用次数用完。access_token 每天 2000 次，客服消息 50 万次等；看"接口权限"页的当日用量，可以调 clear_quota 清零（每月 10 次）。 |
45010 | 创建菜单个数超过限制 | menu count out of limit | — |
45011 | API 调用太频繁，请稍候再试 | api minute-quota reach limit | 分钟级频率限制，多半是登录 / 重试进了循环。 |
45015 | 回复时间超过限制 | response out of time limit or subscription is canceled | 客服消息只能在用户 48 小时内有互动的情况下发。 |
45047 | 客服接口下行条数超过上限 | out of response count limit | 用户一次互动后最多回 20 条。 |
45064 | 创建菜单包含未关联的小程序 | invalid weapp appid | 先在公众号后台"小程序管理"里关联该小程序。 |
45065 | 相同 clientmsgid 已存在群发记录，返回数据中带有已存在的群发任务的 msgid | clientmsgid exist | — |
45066 | 相同 clientmsgid 重试速度过快，请间隔 1 分钟重试 | clientmsgid too fast | — |
45067 | clientmsgid 长度超过限制 | clientmsgid size out of limit | — |
46001 | 不存在媒体数据 | media data missing | — |
46002 | 不存在的菜单版本 | invalid menu version | — |
46003 | 不存在的菜单数据 | menu no exist | 还没创建过菜单就去查 / 删。 |
46004 | 不存在的用户 | invalid openid | — |
47001 | 解析 JSON/XML 内容错误 | data format error | body 不是合法 JSON：单引号、尾逗号、注释、BOM 头都会导致。 |
47003 | 模板参数不准确，可能为空或者不满足规则 | argument invalid | 订阅消息字段类型和长度限制（thing 20 字、number 32 位纯数字等），字段要包成 { value }，不能缺、不能多。 |
48001 | api 功能未授权，请确认公众号已获得该接口 | api unauthorized | 接口权限与账号类型 / 认证状态相关：订阅号没有网页授权、模板消息等；未认证服务号也缺一批。看后台"接口权限"页。 |
48002 | 粉丝拒收消息（粉丝在公众号选项中，关闭了"接收消息"） | user block receive message | — |
48004 | api 接口被封禁，请登录 mp.weixin.qq.com 查看详情 | api forbidden for irregularities | — |
48005 | api 禁止删除被自动回复和自定义菜单引用的素材 | forbidden delete material | — |
48006 | api 禁止清零调用次数，因为清零次数达到上限 | forbidden clear quota | — |
48008 | 没有该类型消息的发送权限 | no permission for this msgtype | — |
50001 | 用户未授权该 api | user unauthorized | 网页授权 scope 不够（snsapi_base 拿不到用户信息），或第三方平台未被授权该权限集。 |
50002 | 用户受限，可能是违规后接口被封禁 | user limited | — |
50005 | 用户未关注公众号 | user not subscribe | — |
61451 | 参数错误 (invalid parameter) | invalid parameter | — |
61452 | 无效客服账号 (invalid kf_account) | invalid kf_account | — |
61453 | 客服帐号已存在 (kf_account exsited) | kf_account exsited | — |
61454 | 客服帐号名长度超过限制（仅允许 10 个英文字符，不包括 @ 及 @ 后的公众号的微信号） | invalid kf_acount length | — |
61455 | 客服帐号名包含非法字符（仅允许英文 + 数字） | illegal character in kf_account | — |
61456 | 客服帐号个数超过限制（10 个客服账号） | kf_account count exceeded | — |
61457 | 无效头像文件类型 (invalid file type) | invalid file type | — |
61450 | 系统错误 (system error) | system error | — |
61500 | 日期格式错误 | date format error | 统计接口日期格式 YYYY-MM-DD，且 begin_date 与 end_date 跨度有上限（多为 7 天或 1 天）。 |
63001 | 部分参数为空 | some parameter is empty | — |
63002 | 无效的签名 | invalid signature | JS-SDK / 消息签名算法问题，看站内签名调试器。 |
65301 | 不存在此 menuid 对应的个性化菜单 | menuid not exist | — |
65302 | 没有相应的用户 | user not exist | — |
65303 | 没有默认菜单，不能创建个性化菜单 | no default menu | 先用 menu/create 建默认菜单。 |
65304 | MatchRule 信息为空 | matchrule empty | — |
65305 | 个性化菜单数量受限 | conditional menu count limit | — |
65306 | 不支持个性化菜单的帐号 | account not support conditional menu | — |
65307 | 个性化菜单信息为空 | conditional menu empty | — |
65308 | 包含没有响应类型的 button | button without type | — |
65309 | 个性化菜单开关处于关闭状态 | conditional menu switch off | — |
65310 | 填写了省份或城市信息，国家信息不能为空 | country empty | — |
65311 | 填写了城市信息，省份信息不能为空 | province empty | — |
65312 | 不合法的国家信息 | invalid country | — |
65313 | 不合法的省份信息 | invalid province | — |
65314 | 不合法的城市信息 | invalid city | — |
65316 | 该公众号的菜单设置了过多的域名外跳（最多跳转到 3 个域名的链接） | too many domains | view 类型按钮的 url 最多 3 个不同域名。 |
65317 | 不合法的 URL | invalid url | — |
87009 | 无效的签名 | invalid signature | 开放平台 / 小程序侧的签名错误，多与 JS-SDK 或消息推送签名有关。 |
9001001 | POST 数据参数不合法 | invalid post data | — |
9001002 | 远端服务不可用 | remote service unavailable | — |
9001003 | Ticket 不合法 | invalid ticket | — |
9001004 | 获取摇周边用户信息失败 | — | |
9001005 | 获取商户信息失败 | — | |
9001006 | 获取 OpenID 失败 | — |
依据官方《全局返回码说明》，2026-09 查看。微信支付、企业微信有各自独立的错误码体系，不在这张表里。