错误码与限流

统一错误信封

所有非 2xx 响应：

{ "schema":"v1", "code":"OUT_OF_STOCK", "msg":"insufficient inventory at last snapshot", "data":null, "agent_ref":"your-agent" }

agent_ref 回显你的 agent 标识，便于排查你自己的调用日志。

错误码总表

code	HTTP	含义	你该做什么
`INVALID_PARAM`	400	参数缺失/非法（msg 有细节）	修正参数后重试
`UNAUTHORIZED`	401	key 无效或已停用	检查 key；联系平台换发
`RATE_LIMITED`	429	超出档位限速	指数退避重试（见下）
`OUT_OF_STOCK`	409	库存快照不足	刷新商品后换推荐或减量
`PRICE_CHANGED`	409	价格已变动	重新取价报价
`RECEIVER_INVALID`	400	收货人信息不全/手机号非法	向用户补全信息
`ORDER_NOT_FOUND`	404	单号不存在或不属于你的 key	核对 order_no
`PAY_EXPIRED`	410	30 分钟支付窗口已过	重新 create_order
`UPSTREAM_ERROR`	502	上游履约系统异常	稍后重试；持续失败联系平台
`INTERNAL`	500	平台内部错误	指数退避重试；持续出现联系平台

限流

按 agent key 档位（每分钟请求数）：

档位	限额	适用
`t0_free`	30	试用/低频
`t1_std`	60	默认
`t2_burst`	240	高频（申请制）

超限返回 429 RATE_LIMITED。标准退避：

node

async function withBackoff(fn, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const r = await fn();
    if (r.code !== 'RATE_LIMITED') return r;
    await new Promise(res => setTimeout(res, 1000 * 2 ** i + Math.random() * 500));
  }
  throw new Error('rate limited, give up');
}

python

def with_backoff(fn, tries=4):
    for i in range(tries):
        r = fn()
        if r.get('code') != 'RATE_LIMITED': return r
        time.sleep(2 ** i + random.random() * 0.5)
    raise RuntimeError('rate limited, give up')

NOTE 限流是按 key 全局计（你的所有用户共享你 key 的额度）。把轮询间隔控制在 5 秒以上、缓存商品搜索结果 60 秒，t1 档足够支撑数千级日活用户。

平台侧变更约定

错误码只增不改；字段只增不删
破坏性变更会提前在本站更新日志公告并给迁移期
建议你的解析代码对新字段宽容（未知字段忽略）、对未知 code 走 INTERNAL 分支