错误码总表
两类来源：中台自定义 code（响应里的 code）与微信 errcode（errcode 字段或消息里的括注）。
按 code 分支处理，不要按 msg 文案判断。
鉴权与签名
| code | HTTP | 原因 | 怎么办 |
|---|
| site_missing | 401 | 没带 X-Hub-Site | 补上站点短码 |
| site_unknown / site_off | 401 / 403 | 短码不存在或站点已停用 | 核对后台「接入站点」 |
| secret_missing | 401 | 站点从未生成密钥，或重置后没同步 | 后台重置一次，抄进站点配置 |
| sign_format | 401 | 签名不是 64 位小写十六进制 | 常见于 base64、大写、或带了 sha256= 前缀 |
| sign_window | 401 | 时间戳偏差超过 300 秒 | 先给服务器对时，别改容差 |
| sign_mismatch | 401 | 签名不一致 | 用签名计算器双方比对签名串。最可能：body 被重新编码、path 带了域名或 query、用错密钥 |
| nonce_replay | 401 | nonce 在窗口内重复 | 每次请求生成新 nonce；别缓存整个请求对象 |
| ip_denied | 403 | 调用方 IP 不在站点白名单 | 加上出口 IP，或清空白名单只靠签名 |
| rate_limited | 429 | 站点日调用上限触发 | 检查是否写了循环重试；需要提额找中台管理员改设置 |
登录中转
| code | 原因 | 怎么办 |
|---|
| return_not_allowed | 回跳域名不在白名单 | 改传相对路径，或在站点里加 allowed_hosts |
| return_scheme / return_host / return_long | 回跳地址不合法 | 必须 https 或站内相对路径，不含用户名口令、不超 400 字符 |
| home_missing | 站点没登记主页 | 后台补 home_url（https 完整地址） |
| state_unknown / state_used / state_expired | 授权上下文丢失 | 正常现象：用户重复点返回、或超时。从站点重新发起登录即可 |
| code_missing | 用户在授权页点了拒绝 | 提示用户重试并允许授权 |
| oauth_exchange | code 换 openid 失败 | 看括注的微信 errcode：40029=code 已被用（不要重复兑换）；10003=授权域名不对 |
| ticket_invalid / ticket_unknown / ticket_expired | 票据缺失或超时 | 站点必须"跳回来第一件事就是兑换"；60 秒内完成 |
| ticket_used | 票据已兑换 | 说明站点重复请求了。检查是否刷新了两次页面 / 前端预取 |
| ticket_site | 票据属于别的站点 | 多站点共用了同一个回调地址，按 hub_site 参数分流 |
| scope_denied | 站点没开该能力 | 后台勾选对应 scope |
| profile_missing / profile_incomplete | 中台侧账号未配或缺密钥 | 找中台管理员，看诊断台哪一项红 |
支付
| code / 微信码 | 原因 | 怎么办 |
|---|
| pay_disabled | 中台收款开关未打开（503） | 通道自检通过、1 分钱实测之后再开 |
| pay_denied | 站点没有收款权限 | 后台勾选 allow_pay + scope |
| channel_not_ready | 凭据不齐 | 错误文案会指出缺什么：私钥不可读 / APIv3 长度不对 / 序列号填成公钥 ID / 公钥与平台证书混填 |
| bad_out_trade_no | 单号格式不符 | 6–64 位字母数字-_，建议带站点前缀避免撞号 |
| amount_range | 金额越界 | 单位是分；检查是否把元当成分传了 |
| openid_required | jsapi/miniprogram 场景没带 openid | 先走登录中转拿身份，或改用 scene=cashier 让收银台自己静默授权 |
| order_conflict | 同单号不同金额 | 不允许改价重试：撤单换号，或原单继续付 |
| order_bad_state | 原单已关闭/已退款 | 用新单号重新下单 |
| APPID_MCHID_NOT_MATCH | AppID 与商户号没关联 |
商户平台 → 产品中心 → APPID 账号管理 发起关联，再去公众平台「微信支付」确认。申请单 7 天失效、绑定后不可解绑；异主体需签承诺函 |
| NO_AUTH | 商户号未开通该支付产品 | 产品中心申请 JSAPI / Native / H5 |
| SIGN_ERROR | 签名被拒 | 序列号必须是商户 API 证书序列号（40 位十六进制），不是 PUB_KEY_ID_；或私钥与证书不配对 |
| PARAM_ERROR | 参数错误 | 最常见：openid 不属于下单 AppID；notify_url 不是 https |
| ORDERPAID | 订单已支付不能关单 | 中台会自动转查单入账，不需要人工干预 |
| order_missing（回调里） | 回调找不到单 | 说明下单与回调不是同一通道；检查 ?ch= 参数是否被改写 |
| verify failed / decrypt failed | 回调验签或解密失败 | 验签公钥没配（或模式选错）、APIv3 密钥不对。修好之前回调一律不 ACK，让微信继续重试 |
消息
| code / errcode | 原因 | 怎么办 |
|---|
| template_missing | 事件没配模板 | 后台「消息模板」拉取微信模板一键生成 |
| bad_event / bad_openid | 参数不合法 | openid 来自 exchange 返回；event_key 小写字母开头 |
| openid_unresolved | unionid 找不到 openid | 该用户还没走过登录中转；或账号未绑开放平台导致没有 unionid |
| 43004 / 40003 | 不是本账号粉丝 / openid 无效 | 引导关注，或降级到短信/站内 |
| 43101 | 未订阅或额度用完 | 用订阅引导页攒额度 |
| 45009 | 账号日配额耗尽 | 等退避（与 edusoho 共享配额），别狂点重发 |
| rate_limited（skipped） | 触发中台的每人每日上限 | 正常保护。要发更多说明事件设计有问题，先合并不是提额 |
微信公共错误码（任何接口都可能出现）
| errcode | 含义 | 怎么办 |
|---|
| -1 | 系统繁忙 | 稍后重试，中台已按退避重试 |
| 40001 / 42001 | access_token 无效或过期 | 中台会自动重取一次；持续出现说明 IP 或 Secret 有问题 |
| 40013 | AppID 不合法 | 检查填错、空格、大小写 |
| 40125 | AppSecret 无效 | 微信开发者平台重新复制；重置后旧值立即失效 |
| 40164 | 调用 IP 不在白名单 | 加本机出口 IP（微信账号页顶部能看到） |
| 41001 | 缺少 access_token | 中台侧问题，报给管理员 |
| 43002 | 需要 POST | 接口方法用错 |
| 45011 | 分钟级频控 | 降低并发，别重试打爆 |
| 48001 | 接口未开放/无权限 | 确认账号类型与已开通能力（如未认证服务号没有模板消息权限） |
| 89503 / 89506 | 调用需管理员确认或被拒绝 | 与管理员确认后 1 小时/24 小时后再试 |
报错时先做这三件事
- 打开接口日志，按方向筛出那条记录，看「详情」里的请求与响应原文（已脱敏）。
- 跑一次深度自检，看是不是 IP 白名单 / Secret / 域名配置这类基础问题。
- 还不行就下载「排查包」发给中台管理员，里面有全部体检结论与最近 15 条错误。
本页内容随代码一起版本化（V0.1.0）。发现文档与实际行为不一致，请当缺陷报告。