全局错误码¶

企业应用每次调用接口时，可能获得正确或错误的返回码，企业可以根据返回码信息调试接口，排查错误。

如果请求的参数不符合 json 规范（如类型不匹配、格式有问题），可能会导致企业微信解析到的参数不完整，此时接口在返回的 errmsg 里会有 “Warning: wrong json format.”，开发者需要重新检查请求参数的 json 合法性。

全局返回码¶

排查方法¶

错误码：40001¶

不合法的 secret 参数，常见的原因如下：

1. 调用接口传参问题，实际没有传入到 secret 和 corpid 参数。
2. 传入的企业 corpid 与 secret 不匹配，比如重置了应用的 secret，但应用程序仍用旧的 secret 调用。
3. 应用已经停用。

错误码：40003¶

不合法的 UserID。确认：

1. 有效的 UserID 需要满足：长度 1~64 字符，由英文字母、数字、中划线、下划线以及点号构成。
2. 除了创建用户，其余使用 UserID 的接口，还要保证 UserID 必须在通讯录中存在。 3.企业内部自建应用，userid 使用明文 userid，第三方应用则需要使用密文 userid。 4) 已离职或已删除成员，userid 会从通讯录中移除，userid 无效 5) 接口文档要求请求方式为 POST 请求，实际调用中使用 GET 请求，导致 UserID 无效。

错误码：40007¶

不合法的媒体文件。确认：

1. 媒体文件 ID 的获取方式。例如发表客户的朋友圈的 media_id，需要用上传附件资源获取；创建企业群发消息的 media_id，用上传临时素材获取。 2) 文件是否过期。注：上传临时素材生成的 media_id，有效期是 3 天。
2. 媒体文件类型应符合接口要求（比如发送图片消息，此时不能用音频文件的 media_id）。

错误码：40014¶

access_token 参数错误。确认：

1. access_token 需要在有效期内调用，失效了就是会提示 token 非法。可以重新获取一次 access_token 解决
2. openapi 解析不到传入的 access_token，可以先检查入参是否存在非法字符，导致无法解析 access_token。
3. access_token 对应的应用类型不匹配，比如小程序登入流程，使用了是非小程序应用的 access_token。
4. token 类型用错，token 分为 access_token suite_access_token 和 provider_access_token 三种，接口对应的 access_token 取值是不一致的，参数名也不一样。需要确认 token 类型。

错误码：40029¶

oauth_code 参数错误。确认：

1. code 只能消费一次，不能重复消费。比如说，是否存在多个服务器同时消费同一 code 情况。
2. code 需要在有效期间消费（5 分钟），过期会自动失效。

错误码：40032¶

不合法的 UserID 列表长度。确认：

1. 发消息接口，最多指定 1000 人。
2. 批量删除成员接口，最多指定 200 人。

错误码：40035¶

不合法的参数。确认：

1. userlist 和 partylist 不能同时为空
2. userlist 包含的成员个数不能大于 1000
3. partylist 包含的部门个数不能大于 100
4. 指定的 userlist 和 partylist 为数组格式，不是字符串格式。比如说， "userlist":[ "user1","user2"]，而不是 "userlist": "user1|user2"

错误码：40054 40055¶

菜单设置 URL 不合法。确认：

1. 链接需要带上协议头。以 http:// 或者 https:// 开头。比如：https://work.weixin.qq.com
2. 微信支付的链接，必须以 weixin://wxpay/bizpayurl 开头

错误码：40056¶

agentid 不合法。确认：

1. agentid 为整型数字
2. 在 web 管理端存在该应用

错误码：40058¶

请求参数不合法。常见的有以下原因：

1. json 不合法，请检查请求体格式是否符合 json 语法。
2. 参数值的长度超出了限制，例如 userid 长度是 64 字节以下，若超过 64 字节则报错 40058。参数字段若是数组类型，若元素个数超出限制，也同样报错 40058.
3. 部分接口要求参数必填（如提交审批接口，要求申请人 userid 必填）时，如果输入参数值为空则报此错误。
4. 撤回消息时报错，请检查发消息和撤回消息是否同一个应用。
5. 当接口要求请求方式为 POST 时，实际调用中使用了 GET 方式，则接口会因为获取不到请求体参数而报此错误。

错误码：40063¶

必填的参数缺少，需要参照具体 API 接口说明。同时确认：

1. Http 请求方法，是否正确。比如说接口要求以 Post 方法，就不能使用 Get 方式
2. Http 请求参数，是否正确。比如说，接口内容要求 json 结构体，就不能以 url 参数传递或者 form-data 方式。

错误码：40070¶

指定的标签范围结点全部无效。确认：

1. 指定的参数格式是否正确。比如，"userlist":[ "user1"]，而不是指定为 "userlist" : "user1"。
2. 指定的成员或者部门，是否存在于通讯录中。

错误码：40082¶

suite_access_token 参数错误。请确认：

1. suite_access_token 是否已过期，suite_access_token 有效期为 2 小时，超时后请重新获取。
2. 请检查传入的 suite_access_token 前后是否有非法字符。

错误码：40084¶

不合法的永久授权码。确认：

1. 是否填写有误
2. 企业是否已取消授权该套件
3. 永久授权码不能跨服务商使用

错误码：40092¶

导入文件存在不合法的内容。确认：

1. 不允许上传空文件
2. 文件内容缺少必填字段，比如：手机/邮箱，姓名，UserID 或者部门。

错误码：40093¶

jsapi 签名错误。请确认：

1. 用于签名的 jsapi_ticket 是否是正确的，是否过期。 可以通过接口获取最新的 jsapi_ticket，与用于签名计算的 jsapi_ticket 比对是否一致。
2. 签名的 URL 要以当前页面 URL 填写，包括页面路径，但不包含#符号及#符号后面部分。
3. 检查签名的时间截是否以秒为单位。

错误码：40096¶

不合法的外部联系人 userid。请确认：

1. 若调用者是企业，请使用企业主体下的 external_userid。
2. 若调用者是第三方服务商，使用服务商主体下的 external_userid。
3. 外部联系人对应的跟进成员要在应用可见范围

错误码：41001¶

缺少 access_token 参数。请确认:

1. access_token 参数值是否正确，access_token 不能为空。
2. access_token 需要拼接在 URL 中，不能放在请求包体中。

错误码：41019¶

缺少 department 参数。确认：

1. 创建成员接口，成员所属部门是必填信息。
2. 所属部门是数字数组格式，不是字符串。如："department: [1, 2]

错误码：45002¶

消息内容大小超过限制。确认：

1. 文本消息类型：最长不超过 2048 个字节。
2. 图文消息类型：最长不超过 666k 个字节

错误码：45009¶

接口调用超过限制。

1. 具体频率策略，参考：主动调用频率限制
2. 频率拦截时长一般与调用的限制时长相同，比如说是分钟级别的限制，则在中频率后的 1 分钟后自动解除。小时、天、以及月份，也是以此类推。

3. 我们对接口调用的频率限制是比较宽松的。对于接口中频率的调用，考虑以下优化：

4. 接口实现时，仅系统失败需要重试。其余错误码，应该排查下调用失败原因

5. 发消息应该控制合理调用，对于单个成员来说，一天收到大量的推送，体验是不好的

6. 获取 access_token 与获取 jsapi_ticket 务必在服务端发起请求，并在服务端做好缓存，access_token 或 jsapi_ticket 获取之后可以使用 2 小时。

7. 获取 access_token 时，如果应用的 secret 错误多次，会导致同一个 IP 被禁用一小时，所以请先排查该 IP 下有哪些应用的 secret 是错误的，且仍然在不断尝试获取 access_token；如果是重置了应用的 secret，请及时调整获取 access_token 的 secret 配置。
8. 手机号换 userid 的接口，需确保手机号的正确性，若出错的次数超出企业规模人数的 20%，会导致 1 天不可调用。
9. 开发者在调用时，可能会在请求 url 上加上 debug=1 参数以开启 debug 模式，该模式的频率限制很小，每分钟只有 5 次，开发者在正式上线前请务必去掉 debug=1 参数。
10. 部分频率拦截，可自助解封，访问：频率自助解封工具

错误码：45033¶

接口并发调用超过限制。对于需要获取存储数据的接口，例如“获取企业客户列表”等接口，企业微信出于系统保护的考虑，会对同一个企业调用同一个接口做并发数的限制，出现这种限制错误后，请企业调低并发数。如果应用程序有 bug，对于同一个资源持续的获取，也会出现该错误，例如对同一个 media_id 持续调用“获取临时素材”接口。

错误码：45024¶

帐号数量超过上限。请确认：

1. 通讯录是否有无效或者无用的帐号，可以删除，让出额度
2. 提高帐号上限，可以提交重新认证或者申请扩容

错误码：45029¶

回包大小超过上限。请确认：

1. /cgi-bin/user/list：由于通讯录组织架构庞大，建议按部门分别拉取，同时不要指定 fetch_child=1。

错误码：46004¶

用户不存在。常见的错误原因有：

1. userid 描写错误。
2. 根据手机号或邮箱地址查 userid 时，传入的手机号或邮箱不存在企业通讯录中，或者不在应用的可见范围之内。

错误码：48001¶

API 功能未授权。请确认：

1. 如果是调用发票相关接口，企业是否已经认证，且激活人数达到 200。
2. 如果是调用明文 corpid 转换为密文 corpid 的接口，企业与服务商之间是否有授权关系。

错误码：48002¶

API 接口无权限调用，一般是应用的权限与所调用的接口不匹配，开发者调用接口前，请先仔细阅读每个接口的“权限说明”。以下是常见的错误情况：

1. 写通讯录接口，只能由通讯录同步助手的 access_token 来调用。同时需要保证通讯录同步功能是开启的。
2. 通讯录同步助手的 access_token，仅用于同步通讯录，不能用于发消息
3. 设置应用可见范围，仅支持注册定制化安装情况，详情见：设置授权应用可见范围
4. 客户联系相关的接口，只能由系统应用“客户联系”调用，或由配置到客户联系“可调用应用”列表中的自建应用调用，或由申请了客户联系权限的第三方应用/代开发应用调用。 5) 打卡相关的接口，只能由系统应用“打卡”调用，或由申请了打卡权限的第三方应用/代开发应用调用。 6) 第三方应用申请了权限之后，需要重新提交审核发布，发布之后再由授权企业的管理员确认通过后，该类权限才正式生效，才能调用该类接口。 7) 应用群聊会话接口，仅支持自建应用调用，且自建应用的可见范围需要设置为根部门。 8) 非小程序的应用不能调用小程序通知消息。 9) 代开发应用获取 access_token，应使用自建应用获取 access_token 的接口，而非第三方应用获取 access_token 的接口。

错误码：48007¶

API 接口无权限调用，由于客服账号未授权给该应用。请确认：

1. 微信客服相关接口，要求「微信客服->管理帐号、分配会话和收发消息」权限，且授权了对应的客服账号。可在企业管理后台“微信客服”进行权限管理。

错误码：50001¶

redirect_url 未登记可信域名。请确认：

1. 颁发 code 的场景在哪个应用点击的。消费 code 使用的 access_token 是否有该应用权限。（通过查询 access_token 权限可确认）

2. secret 的获取来源

3. 来源于应用：url 的域名，需设置到应用可信域名中。

4. 来源于通讯录同步助手：仅可同步通讯录，不可用于发消息或者消费 code
5. 来源于第三方套件授权：套件中至少有一个应用，设置了该 url 域名为可信域名

6. 来源于管理组：管理组配置的应用列表，至少有一个应用设置了该 url 域名为可信域名

7. url 填写的域名，必须与设置的可信域名 完全匹配（包括端口号）。比如：填可信域名填 qq.com，访问 url 域名为www.qq.com，就不匹配；或者可信域名填www.qq.com，访问url域名为www.qq.com:8008，也不匹配。

错误码：50003¶

应用禁用之后，将无法再调用 api，可在"管理端-应用管理"重新启用该应用。

错误码：60010¶

部门存在循环关系。请确认：

1. 创建部门和更新部门时，指定的 parentid 参数不能是 部门 id 或者 子部门 id

错误码：60011¶

指定的成员/部门/标签参数无权限。请确认：

1. 指定的成员或部门或标签不在应用的可见范围之内。
2. 指定的成员或部门或标签，虽然在应用的可见范围，但应用对这些成员或部门或标签没有编辑权限。例如往标签添加成员时，若标签并非该应用所创建，那么即使该标签在应用的可见范围，也没有编辑该标签的权限。
3. 其他情况一般是应用不满足该接口调用的权限要求，请阅读相应接口说明文档中的“权限说明”。 错误码：60020 不安全的访问 IP。请根据调用的应用类型分别按如下方法确认：
4. 若调用者是企业自建应用或通讯录同步助手，请确认该 IP 是本企业服务器 IP，并已经配置到应用详情的“企业可信 IP”项目中。第三方服务商 IP 不能调用。
5. 若调用者是第三方应用或服务商代开发应用，请确认该 IP 已经配置到“服务商管理后台”-“服务商信息”-“基本信息”-“IP 白名单”。
6. 配置完可信 IP 之后，需要 1 分钟后才生效。

错误码：60111¶

UserID 不存在，有以下常见原因：

1. 需要传入 userid 字段时，传入的 userid 不是一个合法的 userid。
2. 传入的 userid 不在企业通讯录，有以下情况： a) 成员已退出企业 b) 成员被企业删除 c) 成员实际不在通讯录内 d) 成员不在应用可见范围内
3. 对于代开发应用、第三方应用，若已完成 ID 升级，但仍传入企业主体的明文 userid，也会报此报错。

错误码：610015¶

小程序对应的开放平台帐号未认证。请确认：

1. 小程序绑定的开放平台帐号是否已认证。
2. 若开放平台帐号是通过 api 代注册所创建，可通过微信的「认证代注册的帐号」完成认证。

错误码：610017¶

小程序和企业主体不一致。确认：

1. 小程序的主体名称，或者小程序绑定的开放平台帐号主体名称，与企业的主体名称是否一致。
2. 如果小程序、开放平台帐号、企业三者的主体一致，那需要调用接口传入的 openid 与 unionid 是否该小程序获取。

错误码：670001¶

上游企业获取下游企业的 access_token 时，请确认：

1. 传入的 access_token 是否上游应用。
2. 传入的 corpid 与 agentid 是否是通过获取共享范围接口获取。

错误码：72023¶

一般为发票已进入后续报销流程，报销企业公众号/企业微信/App 锁定了发票。

错误码：80001¶

可信域名不正确，未校验域名所有权归属或者可信域名没有 ICP 备案。请确认：

1. 可信域名，只支持全域名匹配，无法通过配置父域来让所有子域都成为可信域名。
2. 可信域名，不支持 IP 地址、端口号及短链域名。
3. 如果确认域名已经通过 ICP 备案，但依然提示这个错误，请尝试重新设置。

错误码：81011¶

无权限操作标签。请确认：

1. 除了通讯录同步助手和通讯录应用，其他应用和管理组都只能操作自己创建的标签。
2. 通讯录同步助手或者通讯录应用，除了能管理自己的标签，还能操作超级管理组创建的标签。

错误码：81013¶

UserID、部门 ID、标签 ID 全部非法或无权限。一般有以下两种原因：

1. 成员、部门或标签已被删除，此种情况需要调整调用接口的接收人参数。
2. 成员、部门或标签被移出应用的可见范围，可在管理端将接收人添加到应用的可见范围内。

错误码：82001¶

指定的成员/部门/标签全部为空。请确认： 参数是否有传递，且至少有一个参数非空。

错误码：84014¶

成员票据过期。确认：

1. user_ticket 有时效性，有效时长由 expires_in 指定。参考接口：根据 code 获取成员信息
2. 若需再次获取用户详情，需要用户重新点击链接后，根据新的 code 获取新的 user_ticket

错误码：84024¶

无注册信息。可能是以下两种情况：

1. 注册流程未完成。
2. 注册成功已超过 24 小时。

错误码：84061¶

接口调用成功的必要条件是客户存在于服务人员的外部联系人好友列表中，有以下情况会导致报 84061 错误：

1. 如果客户删除了服务人员，此时是还存在单向好友关系，可以调用客户联系相关接口。反之，如果是服务人员删除了客户，则不再存在好友关系，无法调用接口。
2. 服务人员开启了免验证的情况下，客户可以跟服务人员进行会话，但是此时并没有真正添加为好友关系，需要服务人员添加好友后才可以调用接口。

错误码：85005¶

域名未通过所有权校验，仅 oauth2 生效，jssdk 功能将受限，请根据调用的应用类型按以下不同方式完成校验：

1. 若调用者是企业自建应用，请登录企业微信管理端，进入应用详情，按照指引完成域名的所有权校验。
2. 若调用者是第三方应用，请登录企业微信服务管理端，进入第三方应用详情，按照指引完成域名的所有权校验。

错误码：86216¶

存在非法会话成员 ID。确认：

1. 添加会话成员时，指定的成员 ID 不存在通讯录
2. 删除会话成员时，指定的成员 ID 不存在于会话中

错误码：86220¶

指定的会话参数不合法。请确认：

1. 参数 type 只能指定 single/group
2. 参数 msgtype 只能指定 text/image/file/voice/link

错误码：90208¶

小程序 appid 不匹配。有以下常见原因：

1. 小程序没有关联到企业，此时若调用发送消息接口发送小程序，会报此错误。
2. 移动端 sdk 设置的 agentid 非小程序应用的 agentid，此时调用分享接口分享该小程序，会报此错误。

错误码：91040¶

获取 ticket 的类型无效。jsapi ticket 可以通过以下几种获取：

1. 获取 jsapi_ticket。这里参数只需要传 access_token，不需要带其余的参数，比如 type=jsapi
2. 获取电子发票 ticket。需要同时指定 access_token 及 type，同时 type=wx_card 是固定的。

错误码：92002¶

不允许跨企业调用。有以下常见错误：

1. agentConfig 调用时执行成员所在企业和传入的参数 corpid 不匹配
2. 会话存档获取到的群聊不是本企业创建的，而是另外的企业创建的客户群

错误码：301002¶

无权限操作指定的应用。access_token 来源需要有指定应用的权限。 比如说，发消息接口 指定了参数 "agentid": 14，但使用的 access_token 是通过应用 agentid: 100032 生成的调用凭证，这种就会报该错误码。 access_token 的权限查询，可在 错误码查询工具 确认。

错误码：301025¶

审批开放接口参数错误。常见的错误有：

1. 参数输入的值为空或 null，需要填入正确的值。
2. 提交的数据格式与模板不一致，可以获取审批申请详情对比。

错误码：301036¶

不允许更新该用户的 userid。确认： 只有当 userid 由系统自动生成时，才被允许修改一次 比如，邀请关注时用户提交登记信息，审批通过后系统会自动分配 userid，此时可修改 userid

错误码：301055¶

无审批应用权限/无审批应用数据拉取权限。常见的错误原因有：

1. 应用没有审批权限，自建应用需要配置到审批应用的可调用应用列表里，第三方应用需要在应用详情内开启审批权限。
2. 离职成员 userid 不支持作为过滤条件拉取表单记录，当传入离职成员的 userid 时也会提示无审批权限。
3. 传入的参数异常，无法解析出传入的参数内容，例如无法解析出 userid。