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

# 速率限制

> Fluz 针对各服务应用保护性速率限制以保持平台稳定。本文介绍限制内容、429 的返回形式，以及如何构建遵守限制的客户端。

Fluz 不按套餐出售 API 配额——不存在“免费版 = 每分钟 X 次请求、专业版 = 每分钟 Y 次请求”的分级，也没有按密钥分配的配额系统。取而代之的是，每个服务都会应用**保护性速率限制**来吸收滥用并保护其后端。正常的交互式与应用流量几乎不会触达这些限制；它们的存在是为捕捉失控脚本与滥用行为。

<Info>
  没有可公开申请提升的按套餐配额。如果一个行为良好的集成触达了限制，通常意味着存在值得修正的流量模式（参见[构建行为良好的客户端](#build-a-well-behaved-client)），而不是需要提升的配额。
</Info>

## 限制如何应用

限制是**按服务**独立强制执行的，并在该服务的所有实例之间全局评估——无法通过落在不同服务器来规避限制。一次请求通过以下组合来识别：

* **你的 IP 地址**——每个请求都会计入每-IP 的限制。
* **你的访问令牌**——完整的 `Authorization` 头。没有授权头的请求会跳过令牌限制器，但仍计入 IP 限制器，因此请发送一个稳定的令牌，以便按“你”来限速，而不是与共享 IP 的所有人被合并计算。
* **端点路径**——在一些公共界面上，特定路径有其自身限制。

超出任一限制将返回**HTTP `429 Too Many Requests`**。

## 各界面的流量限制

以下为持续的每秒限速。一旦超出，密钥将在短暂冷却期内被阻止，之后才会再次接受请求。

| 界面                                           | 限制          | 超限后的冷却期  |
| -------------------------------------------- | ----------- | -------- |
| **GraphQL API** — 事务型图形端点（`/api/v1/graphql`） | 每秒 20 次请求   | 10 秒     |
| **礼品卡供应商操作**                                 | 每秒 20 次请求   | 10 秒     |
| **社交图谱**（联系人、邀请、关注）                          | 每秒 50 次请求   | 10 秒     |
| **其他服务**（默认）                                 | 每秒 10 次请求   | 下一次请求被拒绝 |
| **移动端 / 应用网关**                               | 按环境调优的保护性限制 | —        |

<Note>
  GraphQL API 端点是多数集成在处理充值、购买、转账与揭示时调用的——请围绕**每秒 20 次请求**进行规划。移动端/应用网关的每 IP、每令牌与每端点限制按环境配置，未公布为固定数值；将其视为保护性限制，并在收到 `429` 时回退。
</Note>

## 认证与安全

登录、PIN 与双重验证（2FA）流程与一般 API 流量分开受保护。重复的失败尝试——登录、PIN 校验或 2FA 验证——以及过多的 2FA 或短信请求会触发临时锁定，并在冷却期后自动清除。成功的认证会重置这些计数器。

<Warning>
  不要自动重试失败的登录、PIN 校验或 2FA。向用户展示“稍后再试”的状态——自动重试会延长锁定时间。
</Warning>

## 当你超出限制时

每个被限流的响应都会使用状态码\*\*`429 Too Many Requests`\*\*。其响应体与头部会随界面不同而变化：

<CodeGroup>
  ```json GraphQL / web / vendor services theme={null}
  {
    "message": "Rate limit exceeded"
  }
  ```

  ```json Gateway / auth services (standardized error) theme={null}
  {
    "success": false,
    "msg": "Too many requests, please try again later",
    "errorRecord": {
      "code": "G-0002",
      "name": "RatelimitExceeded"
    }
  }
  ```
</CodeGroup>

响应头的可用性并不统一：

* **`Retry-After`**（整型秒数）会在认证的 IP 限制器以及 PIN/2FA 流程中返回。对于通用的 GraphQL/web 流量限制器，**不**保证提供。
* 目前**没有**`X-RateLimit-Limit`、`X-RateLimit-Remaining` 或 `X-RateLimit-Reset` 头——不要构建依赖它们的逻辑。

## 构建行为良好的客户端

<Steps>
  <Step title="将 429 视为可重试">
    在出现时遵守 `Retry-After`。若未提供，请采用指数回退，从约 1 秒开始（1s → 2s → 4s…），而非立刻重试。
  </Step>

  <Step title="保持适度的持续速率">
    不要从单一 IP 或令牌并行猛击某个界面。对于 GraphQL API，请将速率稳定维持在每秒 20 次请求以下并平滑突发。
  </Step>

  <Step title="不要自动重试认证失败">
    重复的登录、PIN 或 2FA 失败会导致临时锁定。向用户展示“稍后再试”的消息，而不是自动重试。
  </Step>

  <Step title="发送稳定的访问令牌">
    使用你的令牌为每个请求进行认证，这样基于令牌的限制会专门作用于你的流量，而不是与共享 IP 的其他人合并计算。
  </Step>
</Steps>

由于并非所有地方都保证提供 `Retry-After`，请将你的重试逻辑与[idempotency keys](/concepts/idempotency)配合使用，以确保重试的变更请求不会对一次购买或转账进行双重处理。完整的错误目录请参见[错误](/api-reference/errors)。