鉴权与错误约定

两套鉴权头、统一错误外壳、HTTP 状态与常见错误码。

Bearer：用户身份

用户登录后拿到 access_token（JWT），后续代表该用户的请求带上：

http

Authorization: Bearer <access_token>

登录服务签发的 access_token 在 pay. / api. 等各能力子域通用，无需分别换取。

X-Api-Key：站点身份

http

X-Api-Key: <站点 Key>
Content-Type: application/json

平台按站点 Key 解析出你的 Site 与已开通权限；无权限的能力直接 403。

统一错误外壳

所有对外错误响应体恒为下面这一种形状（平台在网关层统一）：

json

{
  "detail": {
    "code": "permission_denied",
    "message": "未开通权限：公众号通知"
  }
}

code 是稳定机器码，用于前端多语言映射；message 为兜底人读文案。只需解析这一种形状。

HTTP 状态约定

状态	含义
401	缺 Key / Key 无效 / Bearer 无效
403	站点停用或未开通该权限
400	参数错误 / 业务拒绝（见 `code`）
409	冲突（如 JSAPI appid 不匹配、缺付款人 openid）
429	调用过于频繁（限流）
502	上游失败（如 SMTP）
503	平台或站点未绑定配置（邮件 / 对象存储 / 支付 / 微信等）

常见错误码

code	含义
`api_key_missing` / `api_key_invalid`	缺少 / 无效的 X-Api-Key
`site_disabled`	站点已停用
`permission_denied`	站点未开通该能力
`login_code_invalid`	login_code 无效或已用过（一次性、90s）
`validation_error`	请求体字段校验失败（含 user_id/external_customer_id 都没传）
`user_not_registered`	传了 user_id 但在平台不存在（用 external_customer_id 则不涉及）
`wechat_member_not_found`	发模板时该 unionid 从未关注公众号，无法投递
`site_provider_unbound`	站点未绑定该支付渠道配置
`site_wechat_unbound`	站点未绑定公众号配置：请运营在后台「站点接入」为该站点选择一套公众号配置
`site_email_unbound`	站点未绑定邮件配置：请运营在后台「站点接入」选择一套 SMTP 配置
`site_storage_unbound`	站点未绑定存储配置：请运营在后台「站点接入」选择一套存储配置
`content_length_required`	开放预签名缺少 content_length：必传，字节数须与 PUT body 一致
`payment_disabled`	在线支付未启用：联系运营在后台启用支付
`rate_limited`	调用过于频繁（通知每站点 120 次/分钟/类）：降低调用频率后重试
`invalid_time_format`	模板消息 time 格式非法：改为 YYYY-MM-DD HH:MM（可带秒或 YYYY/MM/DD HH:MM）
`payer_mp_openid_missing`	JSAPI 付款人无公众号 openid：引导其先完成 Rekit 微信登录，或回退扫码支付
`jsapi_appid_mismatch`	站点支付 appid ≠ 公众号 appid，无法 JSAPI 下单：运营需在后台改配，此前回退扫码
`order_not_found`	订单不存在或跨站点取单：核对 order_id 与本站点 Key
`checkout_session_not_found`	Checkout Session 不存在或跨站点查询：核对 session id 与本站点 Key