> ## Documentation Index
> Fetch the complete documentation index at: https://end-docs.shallow.ink/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码

> Endfield API 的错误码和错误响应格式说明。

## 响应格式

所有 API 响应遵循统一格式：

```json 成功 theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "code": 0,
  "message": "成功",
  "data": { ... }
}
```

```json 错误 theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "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`   | 配额耗尽     | 等待配额重置或购买量包               |

## 常见错误场景

### 认证相关

```json JWT 过期 theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "code": 401,
  "message": "token已过期"
}
```

处理方式：使用 Refresh Token 刷新，失败则重新登录。

### 游戏凭证失效

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "code": 40301,
  "message": "游戏凭证已过期，请刷新凭证或重新绑定"
}
```

处理方式：清除 `framework_token`，引导用户重新扫码登录。

<Warning>
  `40301` 是游戏凭证错误，**不要**清除 `access_token`。用户的 Web 登录状态仍然有效。
</Warning>

### 速率限制

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "code": 429,
  "message": "请求过于频繁，请稍后再试"
}
```

处理方式：实现退避重试，或升级订阅计划。

### 内容审核拒绝

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "code": 400,
  "message": "内容审核未通过，请修改后重新提交"
}
```

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