发送接口通用错误码

本文适用于文本、图片、文件、语音、视频、链接、名片等消息发送接口。当发送结果中出现负数 ret 值时，表示微信侧发送失败。

首次接入排查

现象	检查
只有掩码，无法复制 Auth	新默认应用在应用凭证页领取一次完整凭证；已有应用用之前保存的值，遗失才在安全设置明确重置
请求地址错误	复制完整 API Base URL 后接 /sendText，保留原有前缀且不要重复拼接
返回成功但手机未收到	核对在线实例的 wId 与目标 filehelper，手机确认前不算发送成功
Webhook 测试成功但没有真实消息	另一个账号从手机手动发送，检查当前应用、订阅与接收日志；见回调说明

错误码列表

错误码	含义	建议处理方式
-2	参数错误	检查请求 Body 是否为合法 JSON，必填参数是否缺失或拼写错误
-21	对方已将你删除，或群不存在	确认目标 wcId 是否正确、对方是否仍在好友列表、群聊是否已解散
-24	消息被过滤或发送过于频繁	降低发送频率，避免短时间向大量目标发送相同内容
-44	需要对方验证，当前不是好友关系	先通过 添加好友 建立好友关系
-96	图片内容或发送行为触发风控	更换图片内容，或降低相同图片的批量发送数量
-104	当前环境异常	查询微信实例在线状态，必要时重新登录或执行 二次登录
-219	当前微信实例不在群聊中	确认当前微信号是否仍在该群中，必要时重新加入

推荐排查顺序

1. 确认微信实例在线：调用 查询在线状态。
2. 确认登录实例：核对 wId 是否属于当前在线微信实例。
3. 确认发送目标：核对 wcId 是否为好友、文件传输助手或有效群 ID。
4. 确认发送频率：同一微信实例发送必须排队，避免并发。
5. 恢复实例连接：如果微信实例离线，确认网络后调用 断线重连。

业务系统处理建议

类型	建议
参数错误	不重试，记录日志并修正请求
目标无效	不重试，标记联系人或群聊不可达
频率过快	延迟重试，并降低该微信实例发送速率
环境异常	暂停发送，先恢复微信实例在线状态
群聊状态异常	更新群聊状态，避免继续向无效群发送

TIP

在业务系统中对发送结果做统一拦截，按错误类型决定是否重试、告警或暂停该微信实例的发送队列。