多数人排查核销报错的方式是搜「错误码 xxx 是什么意思」。这个方法有个前提问题:平台返回的码可能随版本调整,同一现象在不同接口上返回的码也不一致。

一、四类错误来源

来源典型表现占实际问题的比例
凭证层授权失效、token 无效、签名错误接入期最常见
门店层门店不匹配、门店不存在、门店无权限接入期次之,上线后仍有
券状态层券不可用、已核销、已退款、已过期上线后最常见
请求层参数缺失、格式错误、超时、限流联调期集中

先归到哪一层,决定了下一步去查配置、查数据还是查代码。这一步做对,后面就不是盲试。

二、凭证层:先确认「你有没有资格核」

授权是门店级的。判断顺序:

  1. 这个门店有没有完成过授权?(没有 → 先授权,不查别的)
  2. 授权是什么时候拿的?是否长期未使用或已过期?
  3. 商家有没有在后台解除过授权?
  4. 服务端存的授权码有没有被覆盖或丢失?

三、门店层:核销的店和券的店是不是同一家

券是有归属门店的。核销请求里传的门店必须和券的归属门店一致,否则报门店不匹配。三种常见错法:

  • 门店ID 填成品牌/连锁 ID —— 代表整个品牌,不是单店
  • 门店ID 填成北极星体系的 32 位串 —— 老体系已下线,不通用
  • 多门店场景下映射表配错,顾客选了 A 店、实际请求了 B 店

验证动作:拿接口按门店名称反查一次,把返回值和你填的值逐字符对比。这个动作能在两分钟内排除门店层问题。

四、券状态层:券本身还能不能用

这一层不是 bug,是业务规则。常见情况:

  • 已核销过 —— 重复提交、或顾客已在别处用过
  • 已退款 —— 券状态已关闭
  • 已过期 —— 超过有效期
  • 未生效 —— 有些券有使用起始时间
  • 不适用本门店 —— 券限定门店或限定品类

五、请求层:参数与网络

现象常见原因
参数缺失/格式错误字段名大小写不符、必填项漏传、数值传成字符串
中文乱码未按 UTF-8 编码,或未声明 Content-Type
超时客户端超时设得过短,或网络抖动
限流并发过高、短时重复提交
偶发成功偶发失败多实例配置不一致、时钟偏差、重试无幂等

超时这一项要特别说:超时不等于失败。请求可能已经在服务端生效了,只是响应没回来。所以超时后的重试必须具备幂等性。

六、必须记录的日志字段

没有这些字段,事后只能靠猜。建议每次核销至少记录:

  • 请求时间(带时区)、本地请求ID
  • 门店ID、平台、券码(脱敏后)、券类型
  • 调用的接口名与请求参数摘要
  • 返回码、返回消息、完整响应体(截断到合理长度)
  • 耗时、是否重试、重试次数
  • 最终业务结果(成功 / 已回滚 / 待人工处理)

七、推荐的排查顺序

  1. 这个门店今天有没有成功核销过?没成功过 → 优先查凭证层与门店层
  2. 同一张券在平台后台是什么状态?→ 排除券状态层
  3. 用同一组参数手动调一次接口 → 排除业务代码干扰
  4. 换一张券、换一个门店再试 → 定位是券的问题还是配置的问题
  5. 看日志里的完整响应体,而不是只看错误消息

最后一条最重要。错误消息是给人看的摘要,完整响应体里往往带着具体是哪个字段不合法。

常见问题

报错但后台能看到核销记录,算成功吗?

以平台侧记录的最终状态为准。有记录说明请求已生效,属于「响应丢失」而非「核销失败」,不要重复提交。

能不能靠错误码做自动重试?

只对明确的临时性错误(超时、限流)重试,且必须带幂等。业务类错误(券不可用、门店不匹配)重试无意义。