> ## 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 額度——沒有「Free = 每分鐘 X 次、Pro = 每分鐘 Y 次」的分級，也沒有依金鑰計算的配額系統。取而代之，各服務會施加一個**保護性速率限制**，用來吸收濫用並保護後端。一般互動式與應用程式流量幾乎不會觸及這些限制；它們主要是用來攔截失控腳本與濫用行為。

<Info>
  沒有已公布的每方案配額可供申請提高。如果運作良好的整合仍觸發限制，通常代表值得修正的流量模式（請見 [建立表現良好的用戶端](#build-a-well-behaved-client)），而非需要提高的配額。
</Info>

## 限制如何套用

限制會在**每個服務**各自強制執行，並在該服務的所有實例上以全域方式評估——無法透過落在不同伺服器來規避限制。請求會以以下組合進行識別：

* **你的 IP 位址**——每個請求會計入每個 IP 的限制。
* **你的存取權杖**——完整的 `Authorization` 標頭。沒有授權標頭的請求會略過權杖限制器，但仍會計入 IP 限制器，因此請送出穩定的權杖，以便以「你」為單位受限，而不是與共用 IP 的所有人混在一起。
* **端點路徑**——在部分公開介面上，特定路徑有其各自的限制。

超出任何限制將回應 **HTTP `429 Too Many Requests`**。

## 各介面之流量限制

以下為持續性每秒限制。當超出時，該鍵會被封鎖一段短暫冷卻時間，之後才會再次接受請求。

| Surface                                     | Limit       | Cooldown after exceeding |
| ------------------------------------------- | ----------- | ------------------------ |
| **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` 並非在所有地方都有保證，請將重試邏輯與 [冪等鍵](/concepts/idempotency) 搭配使用，確保重試的變更操作不會讓某筆購買或轉帳被處理兩次。完整的錯誤目錄請見 [Errors](/api-reference/errors)。