响应格式与错误

所有接口均使用统一响应格式。

成功响应

{
  "ok": true,
  "requestId": "1c02c8f6-5c39-4b6b-8d3e-bf95fa18d58f",
  "data": {}
}

错误响应

{
  "ok": false,
  "requestId": "1c02c8f6-5c39-4b6b-8d3e-bf95fa18d58f",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request body validation failed",
    "details": []
  }
}

通用响应头

头	说明
`X-Request-Id`	请求 ID，用于排错和日志检索
`Cache-Control: no-store`	禁止缓存敏感响应

常见错误码

错误码	HTTP 状态码	说明
`UNAUTHORIZED`	`401`	缺少必需的鉴权头
`INVALID_API_KEY`	`401`	API Key 不存在或类型不匹配
`API_KEY_DISABLED`	`403`	API Key 已禁用
`INVALID_JSON`	`400`	请求体不是合法 JSON
`INVALID_REQUEST`	`400`	请求体或参数校验失败
`CUSTOMER_NOT_FOUND`	`404`	指定客户不存在
`PLAN_NOT_FOUND`	`404`	指定套餐不存在
`SUBSCRIPTION_NOT_FOUND`	`404`	指定订阅不存在
`FEATURE_NOT_FOUND`	`404`	功能不存在，或不属于该订阅
`CODE_NOT_FOUND`	`404`	卡密不存在
`CODE_ALREADY_REDEEMED`	`409`	卡密已被兑换
`NO_ACTIVE_ENTITLEMENT`	`404`	当前没有有效授权来源
`INSUFFICIENT_QUOTA`	`409`	配额不足
`IDEMPOTENCY_CONFLICT`	`409`	相同幂等键对应的请求体不同
`INVALID_CREDENTIALS`	`401`	用户名或密码错误
`INVALID_ACCESS_TOKEN`	`401`	客户访问令牌无效
`INVALID_REFRESH_TOKEN`	`401`	刷新令牌无效
`TOKEN_EXPIRED`	`401`	访问令牌或刷新令牌已过期
`SESSION_REVOKED`	`401`	会话已登出或吊销
`SIGNATURE_REQUIRED`	`401`	客户端 API Key（Public API Key）启用了强制签名，但请求未签名
`INVALID_SIGNATURE`	`401`	签名错误
`SIGNATURE_TIMESTAMP_EXPIRED`	`401`	签名时间戳超出允许窗口
`SIGNATURE_REPLAYED`	`409`	随机串（nonce）重复使用

分页接口

列表接口使用统一分页参数：

参数	类型	默认值	说明
`page`	number	`1`	页码，从 1 开始
`pageSize`	number	`10`	每页条数，最大 `100`
`search`	string	`""`	搜索关键字

分页响应中的 data 字段结构如下：

{
  "data": [],
  "total": 0,
  "page": 1,
  "pageSize": 10,
  "totalPages": 0
}

成功响应​

错误响应​

通用响应头​

常见错误码​

分页接口​

成功响应

错误响应

通用响应头

常见错误码

分页接口