错误契约

统一信封。按 code 分支，不要按 message 分支 —— Accept-Language

会改变 message，不会改变 code。


{
  "type": "invalid_request_error",
  "code": "insufficient_balance",
  "message": "The member's available balance is not enough.",
  "request_id": "01J8X4K9…"
}

每个响应都带 X-Request-Id，错误体里也带一份。工单第一句话就是它。

type → HTTP → 你该怎么办

type	HTTP	语义	处置
`invalid_request_error`	400	入参不合法或业务前置条件不满足	改正后重发，换新幂等键
`authentication_error`	401	令牌无效 / 过期 / 签名不符	重新换令牌；连续失败查签名串拼法
`permission_error`	403	scope 不足 / IP 不在白名单 / 商户被停用	后台改配置，不要重试
`not_found`	404	对象不存在或不属于本商户	不要重试
`idempotency_error`	409	同键异体 / 首次仍在处理	见「幂等」
`rate_limit_error`	429	超配额	指数退避 + 随机 jitter
`api_error`	500	我方内部错误	同键重试；持续则报工单带 `request_id`
`upstream_error`	502	上游不可用	同键重试
`upstream_timeout`	504	结果不明（可能已执行）	同键重试，或查单确认。绝不换新键

常见 code

code	含义
`member_not_found`	会员不存在或不属于本商户或已停用 —— 三种情况同一响应
`member_context_required`	会员作用域端点缺 `x-on-behalf-of`
`kyc_required`	该业务要求的 KYC 层级未达到。响应体不带层级 —— 各业务的门槛是一张表，去 `GET /v1/kyc/requirements` 取（它按 business 列出 required_level），别按错误响应推断
`insufficient_balance`	会员可用余额不足
`merchant_insufficient_funds`	你的资金账户余额不足 —— 去商户后台充值
`product_not_available`	产品未对本商户授权、已停售或不满足条件
`limit_exceeded`	附 `limit_type`（single/daily/monthly）与 `limit_scope`（member/merchant）
`request_rejected`	风控拒绝的唯一对外码。不带原因、不带规则名、不带评分
`step_up_required`	需强认证，附 `hosted_url` 或 `challenge_id`
`order_not_cancellable`	订单已进入不可撤销阶段
`asset_not_allowed`	该资产不在你的白名单内
`environment_mismatch`	沙盒凭据打了 live 域（或反过来）

两件我方刻意不告诉你的事

风控判据永不出境。 命中原因、规则名、阈值、评分一律不下发。被风控拒绝

时你只会看到 request_rejected。人工申诉走商户后台工单。

跨商户信息不经由错误码泄露。 「该邮箱已注册」「该证件号已用于开卡」

这类响应会暴露另一个商户的会员存在性 —— 一律收敛成同一个不区分的响应。

所以你用一个已属于别处的邮箱建户时，拿到的不是 409。