错误码 - Endfield API

响应格式

所有 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": "内容审核未通过，请修改后重新提交"
}

处理方式：修改蓝图/评论内容，去除违规内容后重新提交。

速率限制与配额