错误码

接口调用失败时，先看返回的 code：

怎样判断调用成功

一次成功的接口响应通常如下，data 中是接口返回的具体数据：

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`

HTTP 200 只表示收到了响应，不代表操作成功。 除了检查 code，下面几种操作还要看：

你在做什么	怎样才算成功
扫码登录	检测二维码返回 `data.status=2`
断线重连	`code=0` 只表示开始恢复；还要检查之后的业务调用，见掉线检测与恢复
测试回调地址	测试投递返回 `data.ok=true`，且 `data.httpStatus` 为 200～299
测试消息收发	发消息后在手机上看到正文；收消息后在自己的服务器读到正文。只看到调用或测试投递成功还不够

这类响应是 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 为 -3004|参数错误，请用 -3004 查上方企微错误码。

卡住的步骤	检查与下一步
只有掩码，无法取得 App Token	新默认应用在应用凭证页领取一次完整凭证；已有应用使用自己保存的完整值。遗失才在安全设置明确重置，旧凭证立即失效
请求地址返回 404	从控制台复制完整 API Base URL，保留 `/wx-api`；业务路径接 `/api/…`，回调配置接 `/webhook/…`，避免重复前缀
发送成功但手机未收到	核对所选实例、当前账号 `uin` 与发送目标；手机确认前不算发送验证完成
测试推送成功但没有真实文本	另一个企微账号从客户端手动发送，核对订阅、实例在线与接收服务日志；按回调排查处理

#	检查	怎么查
1	请求头	`Authorization: Bearer <你的 App Token>` 有没有带、有没有多余空格
2	`appid`	操作已有实例时必传，且要属于当前 App Token；首次获取二维码不传
3	实例在不在线	调获取个人信息，`-2007` 需重新扫码；`-11002` 置为离线并提示，由用户决定是否重新登录
4	参数类型	int64 字段传了字符串会直接报 `-3004` 或 `unmarshal` 错误
5	空集合	不同接口的空结果形态不一样：`data:null`、`list:null`、没有 `data` 键都可能出现，解析要兼容