极客场馆开放平台 · 通用约定与错误码

版本 v1 · 配套文档：加密与签名接入 本页是跨接口的公共约定——响应结构、错误码、幂等、重试、限流，外加一个连通性自检 /ping。按 scope 的接口分别见 会员 / 订单 / 钱包 / 约课 / 签到与消费 / 课程·排课·场地。

---

1. 统一响应

所有接口（成功 / 失败）都返回 HTTP 200，body 结构：

{ "code": 200, "message": "ok", "data": { }, "traceId": "tx_xxx" }

code 是业务码（非 HTTP 状态码）；code != 200 即业务失败。加密通道下整个 body 再套一层 {iv, ciphertext, alg}。

---

2. 错误码表

code	含义	对接方处理
200	成功	—
40101	签名错误 / 缺签名头	检查 AppSecret 与签名算法，不要重试
40102	时间戳过期 / Nonce 重放	同步 NTP；换新 Nonce 重试
40103	AppId 不存在 / 禁用 / 过期 / 门店未开通开放平台	联系门店
40104	凭据未启用加密通道	联系门店重建启用加密的凭据
40105	请求体解密失败	检查 AesKey / IV / AAD
40301	scope 不足	联系门店增加 scope
40302	IP 不在白名单	联系门店报备出口 IP
42901	限流	按 Retry-After 头退避
50001	储值余额不足	提示充值，不要重试
50002	单笔扣款超限 / 幂等冲突（outBizNo 已用但参数不一致）	金额超限改金额；幂等冲突换新 outBizNo
50003	会员 / 订单不存在或不属于该门店	检查参数
5xxxx	服务端错误	指数退避重试，复用同一 outBizNo

---

3. 幂等（写接口必看）

所有 POST 写接口必须传 outBizNo：

• 平台按 (AppId, outBizNo) 全局唯一去重
• 命中已存在记录：返回原响应，业务 code 与首次一致
• 命中但参数不一致：返 50002
• 网络重试请用同一个 outBizNo

---

4. 重试策略

错误	是否重试
5xx / 网络错误 / 超时	✅ 指数退避（1/2/4/8s），复用同一 outBizNo
42901 限流	✅ 按 Retry-After 头退避
40101 / 40102 / 40103 / 40301 / 40302	❌ 配置 / 签名问题，不要重试
50001 余额不足 / 50002 超限/幂等冲突 / 50003 不存在	❌ 业务问题，按提示处理

---

5. 限流

• 默认 20 QPS / AppId（可由门店在创建凭据时调整）
• 超限返 42901 + Retry-After: 1

---

6. 连通性自检 · GET /ping

不消耗 scope，只校验签名。用来在联调期跑通签名/加密链路。响应 data：

{
  "appId": "gk_open_20260527_fjb2ui", "gymId": 1001, "brandId": 67,
  "scopes": "member:read,order:read,wallet:read,wallet:deduct",
  "environment": "prod", "traceId": "tx_abcd1234", "serverTime": 1716700000
}

---

7. 通用 FAQ

Q：响应里 code 是 HTTP 状态码吗？ 不是。code 是业务码，HTTP 永远是 200（除非网络层故障）。看 code == 200 判断成功。

Q：调用日志在哪查？ 全量记录在服务端（含签名失败请求）。排障时把响应头 X-Gk-Trace-Id 告诉门店即可查。