企业应用每次调用接口时，可能获得正确或错误的返回码，企业可以根据返回码信息调试接口，排查错误。 注意：开发者的程序应该根据errcode来判断出错的情况，而不应该依赖errmsg来匹配，因为errmsg可能会调整。 如果请求的参数不符合json规范（如类型不匹配、格式有问题），可能会导致企业微信解析到的参数不完整，此时接口在返回的errmsg里会有 “Warning: wrong json format.” ，开发者需要重新检查请求参数的json合法性。 不合法的secret参数，常见的原因如下： 1) 调用接口传参问题，实际没有传入到secret和corpid参数。 2) 传入的企业corpid与secret不匹配，比如重置了应用的secret，但应用程序仍用旧的secret调用。 3) 应用已经停用。 不合法的UserID。确认： 1）有效的UserID需要满足：长度1~64字符，由英文字母、数字、中划线、下划线以及点号构成。 2）除了创建用户，其余使用UserID的接口，还要保证UserID必须在通讯录中存在。 3）企业内部自建应用，userid使用明文userid，第三方应用则需要使用密文userid。 4) 已离职或已删除成员，userid会从通讯录中移除，userid无效 5) 接口文档要求请求方式为POST请求，实际调用中使用GET请求，导致UserID无效。 不合法的媒体文件。确认： 1）媒体文件ID的获取方式。例如发表客户的朋友圈的media_id，需要用 上传附件资源 获取；创建企业群发消息的media_id，用 上传临时素材 获取。 2) 文件是否过期。注：使用 获取临时素材 接口可获取媒体文件的media_id，有效期均为3天。过期后需要调用相关接口重新获取media_id。 3）媒体文件类型应符合接口要求（比如发送图片消息，此时不能用音频文件的media_id）。 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类型。 oauth_code参数错误。确认： 1）code只能消费一次，不能重复消费。比如说，是否存在多个服务器同时消费同一code情况。 2）code需要在有效期间消费（5分钟），过期会自动失效。 3) 颁发code的应用appid跟消费code所使用的应用suiteid不一致。 不合法的UserID列表长度。确认： 1） 发消息接口 ，最多指定1000人。 2） 批量删除成员接口 ，最多指定200人。 不合法的参数。确认： 1）userlist和partylist不能同时为空 2）userlist包含的成员个数不能大于1000 3）partylist包含的部门个数不能大于100 4）指定的userlist和partylist为数组格式，不是字符串格式。比如说， "userlist":[ "user1","user2"]，而不是 "userlist": "user1|user2" 菜单设置URL不合法。确认： 1）链接需要带上协议头。以 http:// 或者 https:// 开头。比如：https://work.weixin.qq.com 2）微信支付的链接，必须以 weixin://wxpay/bizpayurl 开头 agentid不合法。确认： 1）agentid为整型数字 2）在web管理端存在该应用 请求参数不合法。常见的有以下原因： 1) json不合法，请检查请求体格式是否符合json语法。 2) 参数值的长度超出了限制，例如userid长度是64字节以下，若超过64字节则报错40058。参数字段若是数组类型，若元素个数超出限制，也同样报错40058. 3) 部分接口要求参数必填（如提交审批接口，要求申请人userid必填）时，如果输入参数值为空则报此错误。 4) 撤回消息时报错，请检查发消息和撤回消息是否同一个应用。 5) 当接口要求请求方式为POST时，实际调用中使用了GET方式，则接口会因为获取不到请求体参数而报此错误。 必填的参数缺少，需要参照具体API接口说明。同时确认： 1）Http请求方法，是否正确。比如说接口要求以Post方法，就不能使用Get方式 2）Http请求参数，是否正确。比如说，接口内容要求json结构体，就不能以url参数传递或者form-data方式。 指定的标签范围节点全部无效。确认： 1）指定的参数格式是否正确。比如，"userlist":[ "user1"]，而不是指定为 "userlist" : "user1"。 2）指定的成员或者部门，是否存在于通讯录中。 suite_access_token参数错误。请确认： 1) suite_access_token是否已过期，suite_access_token有效期为2小时，超时后请重新获取。 2) 请检查传入的suite_access_token前后是否有非法字符。 不合法的永久授权码。确认： 1）是否填写有误 2）企业是否已取消授权该套件 3）永久授权码不能跨服务商使用 导入文件存在不合法的内容。确认： 1）不允许上传空文件 2）文件内容缺少必填字段，比如：手机/邮箱，姓名，UserID或者部门。 jsapi签名错误。请确认： 1) 用于签名的jsapi_ticket是否是正确的，是否过期。 可以通过接口获取最新的jsapi_ticket，与用于签名计算的jsapi_ticket比对是否一致。 3) 签名的URL要以当前页面URL填写，包括页面路径，但不包含#符号及#符号后面部分。 4) 检查签名的时间截是否以秒为单位。 不合法的外部联系人userid。请确认： 1) 若调用者是企业，请使用企业主体下的external_userid。 2) 若调用者是第三方服务商，使用服务商主体下的external_userid。 3) 外部联系人对应的跟进成员要在应用可见范围 （1）不合法的http请求Range头。某些media_id对应的资源在企业微信后台是加密存储的，如果分片下载，指定下载分片范围只能为16字节的倍数，否则分片解密会失败。需要开发者调整Range头。 （2）请根据请求包中Content-Range返回的range-end+1是否等于size判断是否是最后一个分片。 回包Content-Range说明： Content-Range: bytes <range-start>-<range-end>/<size> 缺少access_token参数。请确认: 1) access_token参数值是否正确，access_token不能为空。 2) access_token需要拼接在URL中，不能放在请求包体中。 缺少 department 参数。确认： 1）创建成员接口，成员所属部门是必填信息。 2）所属部门是数字数组格式，不是字符串。如："department: [1, 2] 消息内容大小超过限制。确认： 1）文本消息类型：最长不超过2048个字节。 2）图文消息类型：最长不超过666k个字节 接口调用超过限制。 1) 具体频率策略，参考： 主动调用频率限制 2) 频率拦截时长一般与调用的限制时长相同，比如说是分钟级别的限制，则在中频率后的1分钟后自动解除。小时、天、以及月份，也是以此类推。 3) 我们对接口调用的频率限制是比较宽松的。对于接口中频率的调用，考虑以下优化： - 接口实现时，仅系统失败需要重试。其余错误码，应该排查下调用失败原因 - 发消息应该控制合理调用，对于单个成员来说，一天收到大量的推送，体验是不好的 4) 获取access_token 与 获取jsapi_ticket 务必在服务端发起请求，并在服务端做好缓存，access_token或jsapi_ticket获取之后可以使用2小时。 5) 获取access_token 时，如果应用的secret错误多次，会导致同一个IP被禁用一小时，所以请先排查该IP下有哪些应用的secret是错误的，且仍然在不断尝试获取access_token；如果是重置了应用的secret，请及时调整获取access_token的secret配置。 6) 手机号换userid的接口，需确保手机号的正确性，若出错的次数超出企业规模人数的20%，会导致1天不可调用。 7) 开发者在调用时，可能会在请求url上加上debug=1参数以开启debug模式，该模式的频率限制很小，每分钟只有5次，开发者在正式上线前请务必去掉debug=1参数。 8) 部分频率拦截，可自助解封，访问： 频率自助解封工具 企业人数已达到上限，添加成员失败。 1）若当前企业未认证，管理员可前往管理后台进行 认证 ，成员可联系管理员认证，认证后可继续添加更多成员。 2）若当前企业已认证或已验证，管理员可前往管理后台申请 扩容 ，成员可联系管理员扩容，扩容后可继续添加更多成员。 回包大小超过上限。请确认： 1）/cgi-bin/user/list：由于通讯录组织架构庞大，建议按部门分别拉取，同时不要指定fetch_child=1。 接口并发调用超过限制。对于需要获取存储数据的接口，例如“获取企业客户列表”等接口，企业微信出于系统保护的考虑，会对同一个企业调用同一个接口做并发数的限制，出现这种限制错误后，请企业调低并发数。如果应用程序有bug，对于同一个资源持续的获取，也会出现该错误，例如对同一个media_id持续调用“获取临时素材”接口。 接口并发调用过程中出现数据操作冲突。企业微信出于保护数据正确性的考虑，在某些场景会下，会禁止接口同时修改同一条记录，例如调用“编辑客户企业标签”接口同时对一组客户和成员打标签，或是调用“分配离职成员的客户”接口同时为某个成员分配客户。 数据访问超过限制。在接口调用过程中，因出现异常流量，企业微信出于系统保护的考虑，会对出现异常流量的数据进行访问限制。当出现此错误时，企业/服务商可以尝试调整参数、适当降低调用频率、并发等措施并进行重试；如果调用接口的频次，并发都在合理范围内，则需要排查当前企业下是否存在使用非官方的企业微信客户端的情况。 用户不存在。常见的错误原因有： 1) userid描写错误。 2) 根据手机号或邮箱地址查userid时，传入的手机号或邮箱不存在企业通讯录中，或者不在应用的可见范围之内。 API功能未授权。请确认： 1) 如果是调用发票相关接口，企业是否已经认证，且激活人数达到200。 2) 如果是调用明文corpid转换为密文corpid的接口，企业与服务商之间是否有授权关系。

API接口无权限调用，一般是应用的权限与所调用的接口不匹配，开发者调用接口前，请先仔细阅读每个接口的“权限说明”。以下是常见的错误情况： 1）写通讯录接口，只能由通讯录同步助手的access_token来调用。同时需要保证通讯录同步功能是开启的。 2）通讯录同步助手的access_token，仅用于同步通讯录，不能用于发消息 3）设置应用可见范围，仅支持注册定制化安装情况，详情见： 设置授权应用可见范围 4）客户联系相关的接口，只能由系统应用“客户联系”调用，或由配置到客户联系“可调用应用”列表中的自建应用调用，或由申请了客户联系权限的第三方应用/代开发应用调用。 5) 打卡相关的接口，只能由系统应用“打卡”调用，或由申请了打卡权限的第三方应用/代开发应用调用。 6) 第三方应用申请了权限之后，需要重新提交审核发布，发布之后再由授权企业的管理员确认通过后，该类权限才正式生效，才能调用该类接口。 7) 应用群聊会话接口 ，仅支持自建应用调用，且自建应用的可见范围需要设置为根部门。 8) 非小程序的应用不能调用小程序通知消息。 9) 代开发应用获取access_token，应使用 自建应用获取access_token 的接口，而非第三方应用获取access_token的接口。 API接口无权限调用，由于客服账号未授权给该应用。请确认： 1) 微信客服相关接口，要求「微信客服->管理账号、分配会话和收发消息」权限，且授权了对应的客服账号。可在企业管理后台“微信客服”进行权限管理。 redirect_url未登记可信域名。请确认： 1）颁发code的场景在哪个应用点击的。消费code使用的access_token是否有该应用权限。（通过 查询access_token权限 可确认） 2）secret的获取来源 - 来源于应用：url的域名，需设置到应用可信域名中。 - 来源于通讯录同步助手：仅可同步通讯录，不可用于发消息或者消费code - 来源于第三方套件授权：套件中至少有一个应用，设置了该url域名为可信域名 - 来源于管理组：管理组配置的应用列表，至少有一个应用设置了该url域名为可信域名 3）url填写的域名，必须与设置的可信域名 完全匹配 （包括端口号）。比如：填可信域名填qq.com，访问url域名为www.qq.com，就不匹配；或者可信域名填www.qq.com，访问url域名为www.qq.com:8008，也不匹配。 应用禁用之后，将无法再调用api，可在"管理端-应用管理"重新启用该应用。 部门存在循环关系。请确认： 1）创建部门和更新部门时，指定的parentid参数不能是 部门id 或者 子部门id 指定的成员/部门/标签参数无权限。请确认： 1) 指定的成员或部门或标签不在应用的 可见范围 之内。 2) 指定的成员或部门或标签，虽然在应用的可见范围，但应用对这些成员或部门或标签没有编辑权限。例如往标签添加成员时，若标签并非该应用所创建，那么即使该标签在应用的可见范围，也没有编辑该标签的权限。 3) 其他情况一般是应用不满足该接口调用的权限要求，请阅读相应接口说明文档中的“权限说明”。 不安全的访问IP。请根据调用的应用类型分别按如下方法确认： 1）若调用者是企业自建应用或通讯录同步助手，请确认该IP是本企业服务器IP，并已经配置到应用详情的“企业可信IP”项目中。第三方服务商IP不能调用。 2）若调用者是第三方应用或服务商代开发应用，请确认该IP已经配置到“服务商管理后台”-“服务商信息”-“基本信息”-“IP白名单”。 3) 配置完可信IP之后，需要1分钟后才生效。 UserID不存在，有以下常见原因： 1) 需要传入userid字段时，传入的userid不是一个合法的userid。 2) 传入的userid不在企业通讯录，有以下情况： a) 成员已退出企业 b) 成员被企业删除 c) 成员实际不在通讯录内 d) 成员不在应用可见范围内 3) 对于代开发应用、第三方应用，若已完成ID升级，但仍传入企业主体的明文userid，也会报此报错。 一般为发票已进入后续报销流程，报销企业公众号/企业微信/App锁定了发票。 可信域名不正确，未校验域名所有权归属或者可信域名没有ICP备案。请确认： 1）可信域名，只支持全域名匹配，无法通过配置父域来让所有子域都成为可信域名。 2）可信域名，不支持IP地址、端口号及短链域名。 3）如果确认域名已经通过ICP备案，但依然提示这个错误，请尝试重新设置。 无权限操作标签。请确认： 1）除了通讯录同步助手和通讯录应用，其他应用和管理组都只能操作自己创建的标签。 2）通讯录同步助手或者通讯录应用，除了能管理自己的标签，还能操作超级管理组创建的标签。 UserID、部门ID、标签ID全部非法或无权限。一般有以下两种原因： 1）成员、部门或标签已被删除，此种情况需要调整调用接口的接收人参数。 2）成员、部门或标签被移出应用的可见范围，可在管理端将接收人添加到应用的可见范围内。 指定的成员/部门/标签全部为空。请确认： 参数是否有传递，且至少有一个参数非空。 成员票据过期。确认： 1）user_ticket 有时效性，有效时长由expires_in指定。参考接口： 根据code获取成员信息 2）若需再次获取用户详情，需要用户重新点击链接后，根据新的code获取新的user_ticket 无注册信息。可能是以下两种情况： 1）注册流程未完成。 2）注册成功已超过24小时。 接口调用成功的必要条件是客户存在于服务人员的外部联系人好友列表中，有以下情况会导致报84061错误： 1) 如果客户删除了服务人员，此时是还存在单向好友关系，可以调用客户联系相关接口。反之，如果是服务人员删除了客户，则不再存在好友关系，无法调用接口。 2) 服务人员开启了免验证的情况下，客户可以跟服务人员进行会话，但是此时并没有真正添加为好友关系，需要服务人员添加好友后才可以调用接口。 域名未通过所有权校验，仅oauth2生效，jssdk功能将受限，请根据调用的应用类型按以下不同方式完成校验： 1）若调用者是企业自建应用，请登录企业微信管理端，进入应用详情，按照指引完成域名的所有权校验。 2）若调用者是第三方应用，请登录企业微信服务管理端，进入第三方应用详情，按照指引完成域名的所有权校验。 存在非法会话成员ID。确认： 1）添加会话成员时，指定的成员ID不存在通讯录 2）删除会话成员时，指定的成员ID不存在于会话中 指定的会话参数不合法。请确认： 1）参数 type 只能指定 single/group 2）参数 msgtype 只能指定 text/image/file/voice/link 小程序appid不匹配。有以下常见原因： 1) 小程序没有关联到企业，此时若调用发送消息接口发送小程序，会报此错误。 2) 移动端sdk设置的agentid非小程序应用的agentid，此时调用分享接口分享该小程序，会报此错误。 获取ticket的类型无效。jsapi ticket可以通过以下几种获取： 1） 获取jsapi_ticket 。这里参数只需要传access_token，不需要带其余的参数，比如type=jsapi 2） 获取电子发票ticket 。需要同时指定access_token及type，同时type=wx_card是固定的。 不允许跨企业调用。有以下常见错误： 1) agentConfig调用时执行成员所在企业和传入的参数corpid不匹配 3) 会话存档获取到的群聊不是本企业创建的，而是另外的企业创建的客户群 无权限操作指定的应用。access_token来源需要有指定应用的权限。 比如说， 发消息接口 指定了参数 "agentid": 14，但使用的 access_token 是通过应用agentid: 100032 生成的调用凭证，这种就会报该错误码。 access_token的权限查询，可在 错误码查询工具 确认。 审批开放接口参数错误。常见的错误有： 1) 参数输入的值为空或null，需要填入正确的值。 2) 提交的数据格式与模板不一致，可以获取审批申请详情对比。 不允许更新该用户的userid。确认： 只有当userid由系统自动生成时，才被允许修改一次 比如，邀请关注时用户提交登记信息，审批通过后系统会自动分配userid，此时可修改userid 无审批应用权限/无审批应用数据拉取权限。常见的错误原因有： 1) 应用没有审批权限，自建应用需要配置到审批应用的可调用应用列表里，第三方应用需要在应用详情内开启审批权限。 2) 离职成员userid不支持作为过滤条件拉取表单记录，当传入离职成员的userid时也会提示无审批权限。 3) 传入的参数异常，无法解析出传入的参数内容，例如无法解析出userid。 小程序对应的开放平台账号未认证。请确认： 1) 小程序绑定的开放平台账号是否已认证。 2) 若开放平台账号是通过api代注册所创建，可通过微信的「 认证代注册的账号 」完成认证。 小程序和企业主体不一致。确认： 1) 小程序的主体名称，或者小程序绑定的开放平台账号主体名称，与企业的主体名称是否一致。 2) 如果小程序、开放平台账号、企业三者的主体一致，那需要确认调用接口传入的openid与unionid是否该小程序获取。 上游企业获取下游企业的access_token时，请确认： 1) 传入的access_token是否上游应用。 2) 传入的corpid与agentid是否是通过获取共享范围接口获取。