> ## 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 的请求速率限制和配额管理机制。

## 速率限制

### IP 级别限制

所有公开接口受 **IP 级别速率限制**保护：**100 请求/分钟**。此限制独立于订阅计划，适用于所有请求。

### 其他限制

| 限制类型           | 规则                  | 适用范围       |
| -------------- | ------------------- | ---------- |
| **匿名 Token**   | 200 请求/Token（2 小时内） | 匿名访问       |
| **指纹获取 Token** | 10 次/分钟（同一指纹）       | 获取匿名 Token |
| **登录失败锁定**     | 5 次失败锁定 15 分钟       | 账号密码登录     |
| **验证码发送**      | 60 秒/次（同一邮箱）        | 邮箱验证码      |

### 订阅计划限制

每个计划有不同的速率限制（每分钟请求数）：

| 计划       | 速率限制     | 日配额    | 月配额       |
| -------- | -------- | ------ | --------- |
| **Free** | 300 次/分钟 | 10,000 | 30,000    |
| **Pro**  | 600 次/分钟 | 50,000 | 1,000,000 |
| **Plus** | 无限制      | 无限制    | 无限制       |

## 响应头

每个 API 响应都包含配额相关的响应头：

| 响应头                         | 说明                                     |
| --------------------------- | -------------------------------------- |
| `X-Plan`                    | 当前计划名称（`free` / `pro` / `plus`）        |
| `X-RateLimit-Limit`         | 每分钟请求限制（Plus 不返回）                      |
| `X-Quota-Daily-Remaining`   | 日配额剩余（Plus 不返回）                        |
| `X-Quota-Monthly-Remaining` | 月配额剩余（Plus 不返回）                        |
| `X-Paid-Quota-Remaining`    | 付费量包剩余                                 |
| `X-Free-Quota-Remaining`    | 签到配额剩余（当日有效）                           |
| `X-Quota-Source`            | 本次消耗来源：`checkin`（签到）/ `purchase`（付费量包） |
| `X-Free-Quota-Used`         | `true` 表示本次请求消耗了签到配额                   |
| `X-Quota-Pack-Used`         | `true` 表示本次请求消耗了付费量包                   |

## 配额消耗优先级

系统按以下优先级消耗配额：

<Steps>
  <Step title="签到配额（免费）">
    每日签到获得的免费配额优先消耗。签到配额当日 23:59:59 过期。
  </Step>

  <Step title="计划配额">
    Pro/Plus 计划的日/月配额。Free 用户的日/月配额用于 public 级接口。
  </Step>

  <Step title="付费量包">
    购买的请求量包，所有用户均可购买。持有量包的 Free 用户可访问 Pro 级接口。
  </Step>
</Steps>

## 路由访问级别

接口分为三个访问级别：

| 级别           | 说明      | 示例                         |
| ------------ | ------- | -------------------------- |
| **public**   | 所有计划可访问 | Wiki、蓝图浏览、公告               |
| **standard** | Pro 及以上 | 游戏数据查询 (`/api/endfield/*`) |
| **premium**  | Plus 专属 | 暂无                         |

<Tip>
  Free 用户如果持有签到配额或付费量包，也可以临时访问 standard 级接口（提权机制）。
</Tip>

## 超出限制

| HTTP 状态码 | 含义                                |
| -------- | --------------------------------- |
| `429`    | 速率限制或配额耗尽                         |
| `403`    | 计划级别不足（如 Free 访问 standard 接口且无量包） |

建议实现指数退避重试策略：

```javascript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status === 429) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    return response;
  }
  throw new Error('请求超出重试次数');
}
```