未收录错误码与非 errcode 类失败

容易被忽略的错误码（接口专属 / 只有英文说明）

以下错误码要么只写在某个接口的「错误码」小节、未出现在公共/通用返回码表（如 40243、50004、50007、53404 系列），要么虽已收录但官方说明过于简略、缺少中英文对照（如 1003、45035、89503 系列）。它们在同步场景里都真实会出现：

错误码实践中的含义来源与处理
40243AppSecret 已被冻结接口专属：公众号中冻结了 AppSecret，解冻后再同步
50004禁止使用 token 接口接口专属：账号被限制调用 token 接口，需联系公众号管理员核实
50007账号已冻结接口专属：账号处于冻结/注销状态，恢复后再同步
53404 / 53405 / 53406带货能力被限制 / 商品信息有误 / 未开通带货能力接口专属（draft/add 商品字段）：插件不传商品信息，正常不会触发
1003POST 参数非法通用表已收录但只有中文名：多见于 multipart 报文被反向代理改写（未透传 Content-Length / boundary、client_max_body_size 过小被截断）。检查代理是否原样转发请求体
45021某字段可能超出长度限制多由 author（≤ 8 字）这类短字段超限引起；插件已对作者自动截断到 8 字（截断时日志有提示），一般不会触发
45035access clientip is not registered, not in ip-white-list与 40164 同属 IP 白名单校验，个别账号/网段返回这个英文变体；同样去核对白名单 IP
89503此次调用需要管理员确认出口 IP 未加入白名单、走了「管理员确认」流程：在公众号后台确认该 IP 的调用，或直接加入白名单
89506 / 89507该 IP 的调用已被公众号管理员拒绝分别需等待 24 小时 / 1 小时 后重试；长期调用请先与管理员沟通并加入白名单
空 errcode / 返回非 JSON代理返回 HTML 或网关错误页见下方非 errcode 类失败

微信错误码会随版本调整，若上表未覆盖，可在微信开发者平台用官方的「智能 API 诊断」工具，配合响应里的 rid 辅助定位。

非 errcode 类失败

插件的失败提示里若没有 errcode，通常是网络、代理或本地安全策略拦截：

提示原因与处理
「解析微信响应失败：<html>...」收到了 Nginx / 1Panel / CDN 的错误页（常见 403、404、502）。检查 proxy 的 location 是否放行全部 7 个接口路径（含 material/get_material、draft/get、draft/update）、proxy_pass 是否指向 https://api.weixin.qq.com
日志「校验给不出结论（代理未转发该接口 / 限流 / 网络异常等）」复用封面前调用 material/get_material 没拿到结论，插件按保守策略重新上传封面（同步不受影响，也不会打断任务）。若每次同步都出现，先查代理是否放行 /cgi-bin/material/get_material（漏掉它不报错，但每次同步会新增一份封面永久素材），其次看是否被 45009 / 45011 限流或凭证失效（40001 / 42001）
412 Precondition Failed微信网关校验 Content-Length，旧版本 Spring 6.1+ 分块传输曾触发，当前版本已通过手动拼 multipart 并显式设置 Content-Length 修复；若仍出现，确认代理未把请求体重新分块或改写
HTTP 501 Not Implemented，响应体是 waf.tencent.com 的 501 拦截页请求被腾讯云 WAF 按内容风控拦截，根本没到微信接口（所以既没有 errcode 也没有 rid）。微信开放社区有同类记录：请求体里出现 ORDER BY 1、DBMS_PIPE.RECEIVE_MESSAGE() 等注入特征串即被拦。命中的是正文 / 标题里的某个特征串，插件侧无法改写；插件已能兜住：更新草稿时若被这样拦下，会自动改为新建草稿（draft/add 走的是另一套规则，实测存在「更新被拦、新建放行」的组合），因此同步不会失败，只是草稿箱里会多出一份旧草稿（任务记录里的实际动作记为 create，见 MCP 工具；message 里保留 WAF 拦截页开头与「被腾讯云 WAF…拦截」的说明）。也可把 接口地址 改为自建反向代理（换一个出口 IP）再试
其它 4xx / 5xx 状态行（如 502 Bad Gateway）微信的业务错误一律是 HTTP 200 + errcode，出现状态行说明请求被网关 / 代理层挡下、没到接口本身。失败提示里会带上「状态行 + 出错接口 + 响应体摘要」（形如 微信接口返回 HTTP 502 Bad Gateway（POST /cgi-bin/draft/add）：…）：响应体若是自建代理的报文，就查该 location 是否放行全部接口路径（含 material/get_material、draft/get、draft/update）
TLS 握手失败 / SSLHandshakeException代理到上游未开启 SNI（proxy_ssl_server_name on; 与 proxy_ssl_name api.weixin.qq.com;）
请求超时、连接被重置调大代理的 proxy_read_timeout、client_max_body_size；图片多、带宽低时同步耗时本就较长，可等待任务自动出结果
「已拒绝下载：目标发生重定向 xxx」插件的 SSRF 防护禁止跟随跳转：图片地址 301/302 到其它域名。改用不跳转的直链
封面/图片下载失败地址指向内网同上：命中 SSRF 默认策略。公网图片请保证可直接访问，内网图片按内网部署与图片下载白名单放行