代下单 API 常见报错排查：8 种错误码对应处理方案
先建立排查思路
遇到报错，先分三类：
1. 鉴权类（签名、密钥、时间戳）→ 配置问题
2. 业务类（门店、库存、余额）→ 业务状态问题
3. 网络类（超时、限流）→ 稳定性问题
不同类别的处理方式完全不同，别混着查。
8 类常见错误
1. 签名错误 / 鉴权失败
表现：401、sign error、invalid signature
原因：
- Secret 填错或有多余空格
- 参数顺序不对（部分平台要求按字母序拼接）
- 时间戳与服务器差超过 5 分钟
处理：先用平台提供的签名示例代码对照；检查服务器时间是否准确（date 命令）。
2. 余额不足
表现：402、insufficient balance
原因：预充值金额不够，或有大额订单占用
处理：设置余额告警；大促前提前充值。
3. 门店不可用 / 门店不存在
表现：store not found、门店已下线
原因：
- 门店编码错误
- 该门店不支持此券
- 门店临时停业
处理：维护一份门店编码表；失败时提示客户换门店。
4. 参数缺失 / 格式错误
表现：400、missing parameter
原因：必填字段漏了，或手机号、时间格式不对
处理：对照文档逐个字段核；时间统一用 YYYY-MM-DD HH:mm:ss。
5. 请求过于频繁（限流）
表现：429、rate limit
原因：短时间内请求过多
处理：
- 加请求队列，控制并发（建议 ≤5 QPS）
- 失败后指数退避重试（1s / 2s / 4s）
6. 重复下单
表现：duplicate order、订单号已存在
原因：网络超时后重试，但第一次其实成功了
处理：用业务唯一号做幂等。每次下单生成唯一 out_trade_no，重试时复用同一个号。
7. 请求超时
表现：无响应、timeout
原因：平台侧处理慢，或网络抖动
处理：
- 超时时间设 10–15 秒
- 超时后先查订单状态，再决定是否重试（不要盲目重下）
8. 商品/券库存不足
表现：out of stock、券已售罄
原因：该品项暂时无货
处理：提示客户换品项；同步把闲鱼商品下架或标注「暂时缺货」。
一个必备的日志表
建议记录每次调用：
| 字段 | 用途 |
|---|---|
| 请求时间 | 排查时间线 |
| 业务订单号 | 对账 |
| 接口名 | 定位 |
| 请求参数 | 复现 |
| 响应码 | 分类 |
| 响应内容 | 看具体原因 |
有这个表，排查效率能提高好几倍。
最重要的一条
任何重试前，先查状态。
代下单涉及真实出码，重复下单会造成双重扣款和两张券，客户只能用一个，另一个就是你自己的损失。
下一篇回到运营，讲怎么把散客做成回头客。