Appearance
错误码
本页汇总业务响应、企微错误码、鉴权与网关错误。业务成功看数字 code=0；鉴权与网关失败的 code 是字符串，按下方对应表排查。
响应封套
json
{ "code": 0, "data": { }, "detail": "", "message": "ok", "time": "2026-09-11 10:51:00" }| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 数字 0 成功，业务失败为数字 -1 |
data | object / array | 业务数据。失败时可能为空或缺省；在线但无数据的接口成功时也可能没有 data，不代表失败 |
detail | string | 附加明细，通常为空 |
message | string | 成功为 ok；失败形如 -12007|get expired data empty，竖线前是企微错误码 |
time | string | 服务端处理时间 YYYY-MM-DD HH:MM:SS |
区分接口成功与操作完成
业务响应的 code 是数字，0 表示本次调用成功，HTTP 200 不代表业务成功。异步或测试操作还要检查结果：检测二维码看 data.status=2 才算登录成功；断线重连的 code=0 只表示开始恢复；测试投递要确认 data.ok=true 且 data.httpStatus 为 2xx。鉴权与网关错误使用字符串 code，见鉴权与网关错误。
企微错误码
| 码 | 含义 | 处理建议 |
|---|---|---|
-3004 | 参数错误 | 检查字段名与类型，数字 id 不能传字符串 |
-11001 | 请求断线重连 | 调断线重连 |
-11002 | 你已在其他设备上登录 | 不自动重连，置为离线并提示，由用户决定是否重新扫码 |
-2007 | 已下线 | 重新扫码 |
-12006 | checkQr 没带 uuid | 带上 getQr 返回的 uuid |
-12007 | 二维码过期 | 重新 getQr |
-2003 | syncExternal 无增量或游标失效 | 重新全量或换游标 |
-3020 | 用自聊伪房间 roomId 作发送目标 | 给自己发用当前账号 uin |
-4014 | 过期或错误的 uin 作 conversationId | 先 personal/getInfo 取当前 uin |
-4046 | sendMiniProgram 误填 cover 字段 | cover 留空 |
-18000039 | 加好友被限流 | 降频，不要立即重试 |
-18000003 | 无对应好友申请 | — |
-18000059 | 群二维码已停用（群开启了进群验证） | 提示用户，无法直接取码 |
-24001155 | 群发助手无法发送一年前的任务 | 检查任务 id |
-2001 | 大文件下载失败 | fileId 无效或不存在 |
鉴权与网关错误
这类响应是 JSON 对象，code 是字符串，message 是错误说明。例如：
json
{ "code": "invalid_token", "message": "App Token 无效或已重置" }| 错误 | HTTP | 含义 |
|---|---|---|
unauthorized | 401 | 缺少 Authorization 请求头 |
invalid_token | 401 | App Token 格式不正确、无效或已重置 |
proxy_required | 400 | 新建实例未指定代理，省份 region / 自定义代理 socks5 / 本地代理 aid 三选一 |
appid_not_bound | 403 | appid 不属于当前应用，检查 App Token 与实例归属 |
capacity_exhausted | 403 | 实例容量已满 |
rate_limited | 429 | 调用频率超限，降低调用频率后再试 |
device_create_disabled | 403 | 创建设备不对外开放，由 getQr 自动创建 |
not_exposed | 403 | 企微连接由系统维护，相关接口不对外 |
到达业务层后的失败采用另一种格式：code 为数字 -1，企微错误码在 message 的竖线前。例如 message 为 -3004|参数错误，应查上方企微错误码，不要把它当成字符串网关错误。
排查顺序
| # | 检查 | 怎么查 |
|---|---|---|
| 1 | 请求头 | Authorization: Bearer <你的 App Token> 有没有带、有没有多余空格 |
| 2 | appid | 操作已有实例时必传，且要属于当前 App Token；首次获取二维码不传 |
| 3 | 实例在不在线 | 调获取个人信息，-2007 需重新扫码；-11002 置为离线并提示，由用户决定是否重新登录 |
| 4 | 参数类型 | int64 字段传了字符串会直接报 -3004 或 unmarshal 错误 |
| 5 | 空集合 | 不同接口的空结果形态不一样：data:null、list:null、没有 data 键都可能出现，解析要兼容 |
幂等与重试
- 发送类接口不要盲目重试。 重试前先确认上一次是否已成功，否则会重复发给客户。
- 同一个
appid的发送进队列，避免并发直发。 - 加好友类接口遇到
-18000039要降频，不要立即重试。