Skip to main content

​
响应格式

所有 API 响应遵循统一格式：
成功
{
  "code": 0,
  "message": "成功",
  "data": { ... }
}
错误
{
  "code": 400,
  "message": "具体的错误描述信息"
}

​
HTTP 状态码

状态码含义说明
200成功请求正常处理
201创建成功资源创建成功（如发布蓝图）
204无内容删除成功
400请求错误参数格式错误、缺少必填字段
401认证失败Token 无效或已过期
403权限不足计划级别不够或游戏凭证失效
404未找到资源不存在
409冲突资源冲突（如同步任务已在运行）
429请求过多超出速率限制或配额
500服务器错误内部错误，请稍后重试

​
业务错误码

除了 HTTP 状态码，code 字段还可能包含更具体的业务错误码：
错误码含义处理方式
0成功正常处理 data 字段
400请求参数错误检查请求参数
401认证失败刷新 Token 或重新登录
403权限不足升级订阅计划或重新绑定游戏
409同步冲突同步任务已在运行中，等待完成后重试
10003签名/时间戳错误检查请求时间戳是否偏差过大
40301游戏凭证失效清除 Framework Token，重新登录游戏
429配额耗尽等待配额重置或购买量包

​
常见错误场景

​
认证相关

JWT 过期
{
  "code": 401,
  "message": "token已过期"
}
处理方式：使用 Refresh Token 刷新，失败则重新登录。

​
游戏凭证失效

{
  "code": 40301,
  "message": "游戏凭证已过期，请刷新凭证或重新绑定"
}
处理方式：清除 framework_token，引导用户重新扫码登录。
40301 是游戏凭证错误，不要清除 access_token。用户的 Web 登录状态仍然有效。

​
速率限制

{
  "code": 429,
  "message": "请求过于频繁，请稍后再试"
}
处理方式：实现退避重试，或升级订阅计划。

​
内容审核拒绝

{
  "code": 400,
  "message": "内容审核未通过，请修改后重新提交"
}
处理方式：修改蓝图/评论内容，去除违规内容后重新提交。