代金券错误码

一、错误码速查表（TOP 20）

---

二、错误码详细排查

270079501 — openid 与 appID 不匹配

排查步骤：

1. openid 是 AppID 维度的，不同 AppID 下用户 openid 不同

2. 检查 Path 参数 openid 与 Body 参数 appid 是否成对

3. 检查 openid 是否被 URL 编码污染（Path 参数需做 URL 编码）

---

269546525 — 错误的签名，导致验签失败

排查步骤：

1. 检查签名串拼接：HTTP方法\nURL路径\n时间戳\n随机串\n请求体\n（GET 请求 body 为空，末尾仍要 \n）

2. URL 必须用绝对路径（包含 query string，不包含域名）

3. 签名算法 SHA256withRSA，使用商户 API 证书私钥

4. signature 必须是标准 Base64（非 URL-Safe）

5. 建议使用官方 SDK 自动签名

---

269546505 — 商户证书已过期

排查步骤：

1. 登录商户平台 → 账户中心 → API 安全 → API 证书，查看到期时间

2. 重新申请并下载新证书，更新到所有服务节点

3. 建议在证书过期前 30 天监控告警

---

272888874 — KV（内部错误）

排查步骤：

1. 5xx 错误为微信支付侧系统问题，商户侧无需排查参数

2. 使用相同参数稍后重试（指数退避：1s 3s 10s / 30s）

3. 长时间多次重试仍失败时可关注微信支付官方运维公告

---

268573590 — 请求日期超限

排查步骤：

1. 业务服务器开启 NTP 时间同步，确保系统时间准确

2. timestamp 必须是秒级 Unix 时间戳（10 位），不是毫秒

3. 容器化场景下宿主机与容器时区可能不一致，注意校准

---

268586003 — 当天没有退款记录

排查步骤：

1. 接口需在活动结束后次日 10 点之后才有数据

2. 批次活动期间无退款时，确实没有退款明细，业务侧应判断该错误码为「无数据」而非「失败」

---

270079508 — 批次不支持跨商户

排查步骤：

1. 默认批次只允许创建方商户号发放

2. 跨商户发放需在创建批次时勾选「跨商户发放」选项，并在商户平台 → 批次详情 → 委托发券添加授权商户号

3. 检查 stock_creator_mchid 是否传错

---

270079488 — 查询批次为空

排查步骤：

1. 检查查询条件：商户号、时间范围、批次状态是否合理

2. offset 不能超过实际批次总数

3. 业务侧应判断该错误码为「无数据」而非错误

---

270079533 — 活动未开始或已结束

排查步骤：

1. 先调「查询批次详情」（GET /v3/marketing/favor/stocks/{stock_id}）确认当前 status

2. 仅 running 状态可发券；unactivated 需先激活；paused 需先重启

3. 同时检查活动时间窗口：当前时间需在 [available_begin_time, available_end_time] 区间内

---

270079534 — 批次预算不足

排查步骤：

1. 「查询批次详情」查看 max_coupons / max_amount 与已发放数量

2. 可在商户平台 → 营销中心 → 代金券 → 批次详情增加预算（需重新冻结资金）

3. 单天限额耗尽（max_amount_by_day）时第二天 0 点重置

---

268586001 — 当天没有核销记录

排查步骤：

1. 接口需在活动结束后次日 10 点之后才有数据

2. 批次活动期间无核销时，确实没有核销明细，业务侧应判断该错误码为「无数据」

---

270079577 — 批次信息获取失败，请确认参数是否有误

排查步骤：

1. stock_id 长度 ≤ 20 字符，必须是微信支付返回的批次号

2. stock_creator_mchid 必须是创建该批次的商户号，不是发券方商户号

3. 检查 stock_id 大小写、是否被截断、是否被空格污染

---

270079507 — 商户号与 appid 关系校验失败

排查步骤：

1. 登录商户平台 → 账户中心 → API 安全 → AppID 账号管理

2. 把要使用的 appid 添加到当前商户号关联列表

3. 跨商户发券时，请求参数中除 stock_id 和 stock_creator_mchid 外，其他参数（含 appid）都由发放方提供，绑定关系也需在发放方商户号下建立

---

270079509 — 调用方不在可发券商户列表

排查步骤：

1. 批次创建方需在商户平台 → 批次详情 → 委托发券添加调用方商户号

2. 检查批次创建时是否选择了「允许跨商户发券」

3. 朋友圈广告专用批次只能在广告场景发放

---

270079489 — 商户号查询失败

排查步骤：

1. 仔细核对商户号（10 位纯数字），尤其是从配置文件加载时

2. 区分测试环境与生产环境的商户号

3. 服务商场景下区分服务商商户号 sp_mchid 与子商户号 sub_mchid

---

269546507 — 商户证书序列号有误

排查步骤：

1. 登录商户平台 → 账户中心 → API 安全 → API 证书管理，确认当前生效证书序列号

2. serial_no 与签名所用私钥必须是同一对证书

3. 近期重新申请过证书的需更新本地配置

4. 建议使用官方 SDK 自动从证书文件读取 serial_no

---

270079498 — openid 错误

排查步骤：

1. openid 长度 ≤ 128 字符，字符集为大小写字母、数字、下划线 _、连字符 -

2. 检查是否被截断 / 编码污染（Path 参数 URL 编码后未解码）

3. openid 不能为空字符串

4. 服务商场景需要用 sub_openid

---

268461336 — 超过频率限制

排查步骤：

1. 降低发券速率，使用令牌桶限流

2. 大促 / 营销活动场景可提前联系 BD 申请频率上限

3. 重试加 jitter，不要同一秒重发

---

270079532 — 用户被限制领取代金券

排查步骤：

1. 「查询批次详情」查看 max_coupons_per_user，确认上限设置是否合理

2. 用户已达上限时业务侧应记录该用户已领过，避免再次尝试

3. 引导用户在微信完成实名认证可解决部分用户拦截场景

---

269546538 — 商户号不存在

排查步骤：

1. 仔细核对 mchid（10 位纯数字）

2. 区分测试 / 生产环境的商户号

3. 商户号被注销后查不到，无法恢复

4. 服务商场景下确认是 sp_mchid 还是 sub_mchid 传错位置