多数人排查核销报错的方式是搜「错误码 xxx 是什么意思」。这个方法有个前提问题:平台返回的码可能随版本调整,同一现象在不同接口上返回的码也不一致。
一、四类错误来源
| 来源 | 典型表现 | 占实际问题的比例 |
|---|---|---|
| 凭证层 | 授权失效、token 无效、签名错误 | 接入期最常见 |
| 门店层 | 门店不匹配、门店不存在、门店无权限 | 接入期次之,上线后仍有 |
| 券状态层 | 券不可用、已核销、已退款、已过期 | 上线后最常见 |
| 请求层 | 参数缺失、格式错误、超时、限流 | 联调期集中 |
先归到哪一层,决定了下一步去查配置、查数据还是查代码。这一步做对,后面就不是盲试。
二、凭证层:先确认「你有没有资格核」
授权是门店级的。判断顺序:
- 这个门店有没有完成过授权?(没有 → 先授权,不查别的)
- 授权是什么时候拿的?是否长期未使用或已过期?
- 商家有没有在后台解除过授权?
- 服务端存的授权码有没有被覆盖或丢失?
三、门店层:核销的店和券的店是不是同一家
券是有归属门店的。核销请求里传的门店必须和券的归属门店一致,否则报门店不匹配。三种常见错法:
- 门店ID 填成品牌/连锁 ID —— 代表整个品牌,不是单店
- 门店ID 填成北极星体系的 32 位串 —— 老体系已下线,不通用
- 多门店场景下映射表配错,顾客选了 A 店、实际请求了 B 店
验证动作:拿接口按门店名称反查一次,把返回值和你填的值逐字符对比。这个动作能在两分钟内排除门店层问题。
四、券状态层:券本身还能不能用
这一层不是 bug,是业务规则。常见情况:
- 已核销过 —— 重复提交、或顾客已在别处用过
- 已退款 —— 券状态已关闭
- 已过期 —— 超过有效期
- 未生效 —— 有些券有使用起始时间
- 不适用本门店 —— 券限定门店或限定品类
五、请求层:参数与网络
| 现象 | 常见原因 |
|---|---|
| 参数缺失/格式错误 | 字段名大小写不符、必填项漏传、数值传成字符串 |
| 中文乱码 | 未按 UTF-8 编码,或未声明 Content-Type |
| 超时 | 客户端超时设得过短,或网络抖动 |
| 限流 | 并发过高、短时重复提交 |
| 偶发成功偶发失败 | 多实例配置不一致、时钟偏差、重试无幂等 |
超时这一项要特别说:超时不等于失败。请求可能已经在服务端生效了,只是响应没回来。所以超时后的重试必须具备幂等性。
六、必须记录的日志字段
没有这些字段,事后只能靠猜。建议每次核销至少记录:
- 请求时间(带时区)、本地请求ID
- 门店ID、平台、券码(脱敏后)、券类型
- 调用的接口名与请求参数摘要
- 返回码、返回消息、完整响应体(截断到合理长度)
- 耗时、是否重试、重试次数
- 最终业务结果(成功 / 已回滚 / 待人工处理)
七、推荐的排查顺序
- 这个门店今天有没有成功核销过?没成功过 → 优先查凭证层与门店层
- 同一张券在平台后台是什么状态?→ 排除券状态层
- 用同一组参数手动调一次接口 → 排除业务代码干扰
- 换一张券、换一个门店再试 → 定位是券的问题还是配置的问题
- 看日志里的完整响应体,而不是只看错误消息
最后一条最重要。错误消息是给人看的摘要,完整响应体里往往带着具体是哪个字段不合法。
常见问题
报错但后台能看到核销记录,算成功吗?
以平台侧记录的最终状态为准。有记录说明请求已生效,属于「响应丢失」而非「核销失败」,不要重复提交。
能不能靠错误码做自动重试?
只对明确的临时性错误(超时、限流)重试,且必须带幂等。业务类错误(券不可用、门店不匹配)重试无意义。