Skip to main content
Fluz 不會依方案販售 API 配額——沒有「Free = X req/min, Pro = Y req/min」這類分級，也沒有以金鑰為單位的配額系統。每個服務都會套用保護性速率限制，用來吸收濫用流量並保護其後端。一般的互動與應用程式流量實際上幾乎不會觸及這些限制；這些限制的存在是為了攔截失控的腳本與濫用行為。 GraphQL API 也會限制單一查詢能請求的資料量，以成本點數衡量。此限制與請求速率各自獨立，失敗的方式也不同。詳見下方的查詢成本限制。
Fluz 並未公開任何可申請調高的方案配額。如果一個行為正常的整合仍觸及限制，通常代表流量模式需要調整（見打造行為良好的用戶端），而不是配額需要提高。

​
限制如何套用

限制是依服務各自獨立執行，並會在該服務的所有執行個體之間全域評估——你無法透過連到不同的伺服器來規避限制。一項請求會依下列組合來識別：
  • 你的 IP 位址——每個請求都會計入該 IP 的限制額度。
  • 你的存取權杖——完整的 Authorization 標頭。權杖限制是疊加在 IP 限制之上，而非取代它。系統會先檢查 IP 限制，因此來自同一個 IP 的每個請求，無論攜帶哪個權杖，都共用該 IP 的額度。沒有驗證標頭的請求則會略過權杖限制器。
  • 端點路徑——在部分公開介面上，特定路徑有各自的限制。
超過請求速率限制時，會回傳 HTTP 429 Too Many Requests。

​
各介面的流量限制

以下為每秒的持續限制。超過限制時，該金鑰會被封鎖一段短暫的冷卻期，之後才會再次接受請求。
GraphQL API 端點是大多數整合用於儲值、購買、轉帳與卡片資訊顯示的端點——請以每秒 20 次請求為基準來規劃。行動裝置／應用程式閘道的每 IP、每權杖與每端點限制會依環境設定，並未公開固定數字；請將其視為保護性限制，並在收到 429 時進行退避重試。

​
查詢成本限制

GraphQL API 會在執行每個查詢之前先為其評分。只要查詢超過下列任一限制，就會在執行前遭拒絕，無論你放慢請求速度與否都一樣。

​
成本如何計算

你選取的每個欄位都算 1 點。若欄位本身還有選取集，則成本為 1 點加上其內部所有內容成本的 5 倍；查詢的總成本則是所有頂層欄位成本的加總。每多一層巢狀，其下層的成本就會乘以 5：
越深層的欄位成本越高。頂層欄位成本為 1 點，第五層的欄位成本為 625 點，而第六層（深度限制所允許的最深層級）的欄位成本則為 3,125 點。第五層有 11 個欄位，或第六層有 2 個欄位，就會讓查詢超過 7,000。實務上，你會先達到成本限制，才會達到深度限制。
  • 分頁大小不會影響成本。要求 1 筆或 20 筆資料的成本相同，因為成本來自你選取的欄位，而非回傳的資料筆數。
  • __typename 的成本與其他欄位相同。像 Apollo Client 這類預設會在每個選取集中加入它的用戶端，會提高深層查詢的成本。
  • 片段（fragment）會增加層級。內嵌片段（... on Type { }）算作一層巢狀，具名片段展開則算作兩層，因此片段內的相同欄位成本會是原本的 5 倍或 25 倍。大型查詢應將欄位直接展開撰寫，而非使用片段。
  • 文件中的每個操作都會被檢查，包括 operationName 未選取的操作。只要有一個操作超過限制，整個請求就會被拒絕。

​
查詢被拒絕時

回應會是 HTTP 400，原因會列在 errors 陣列中：
即使查詢本身是合法的 GraphQL，訊息開頭仍會顯示 Syntax Error，而 found 的值就是你查詢的成本。別名與指令限制會回傳相同格式、各自的訊息，例如 Syntax Error: Aliases limit of 15 exceeded, found 16.。超過深度限制的查詢一定也會超過成本限制，因此會同時收到兩個錯誤，成本錯誤在前。超過 token 限制的請求會回傳 HTTP 500，代碼相同；批次請求則會回傳 HTTP 400，代碼為 BAD_REQUEST，訊息為 Operation batching disabled.。 查詢遭拒絕時完全不會執行，因此不會套用任何 mutation，再次傳送相同查詢也會得到相同的錯誤。

​
驗證與安全性

登入、PIN 碼與雙重驗證（2FA）流程的保護機制與一般 API 流量分開。重複失敗的嘗試——包括登入、PIN 碼檢查或 2FA 驗證——以及過多的 2FA 或簡訊請求，都會觸發暫時鎖定，並在冷卻期後自動解除。驗證成功會重設這些計數器。
請勿自動重試失敗的登入、PIN 碼檢查或 2FA。應向使用者顯示「請稍後再試」的狀態——自動重試會延長鎖定時間。

​
當你超過限制時

速率限制與查詢成本限制的失敗方式不同，因此重試前請先檢查狀態： 每個受速率限制的回應都會使用 429 Too Many Requests 狀態碼。回應內容與標頭則依介面而異：
標頭的提供並不一致：
  • Retry-After（整數秒）會出現在驗證 IP 限制器與 PIN／2FA 流程中。一般 GraphQL／網頁流量限制器則不保證會提供此標頭。
  • 目前沒有 X-RateLimit-Limit、X-RateLimit-Remaining 或 X-RateLimit-Reset 標頭——請勿建立依賴這些標頭的邏輯。

​
打造行為良好的用戶端

1

將 429 視為可重試

若有提供 Retry-After，請遵循其值。若沒有提供，則從約 1 秒開始進行指數退避（1s → 2s → 4s……），而非立即重試。
2

維持適度的持續速率

不要從單一 IP 或權杖對某個介面平行發送大量請求。對於 GraphQL API，請將速率控制在明顯低於每秒 20 次請求，並平滑處理突發流量。
3

讓查詢保持精簡

只選取你會用到的欄位、保持巢狀層級淺，並在大型查詢中直接展開欄位，而非使用片段。若查詢觸及成本限制，請將其拆成較小的查詢，而不是重試。
4

不要自動重試驗證失敗

重複的登入、PIN 碼或 2FA 失敗會造成暫時鎖定。請向使用者顯示「請稍後再試」的訊息，而不是自動重試。
5

以 IP 而非權杖為單位配置額度

來自同一個 IP 的每個請求都會計入同一個限制，無論使用多少個權杖。如果多個工作程序、服務或客戶帳號透過同一個 NAT 閘道或代理伺服器發送流量，請將它們的速率一併調節，讓合計速率維持在限制之下。
由於 Retry-After 並非在所有情況下都會提供，請將重試邏輯搭配冪等金鑰使用，確保重試的 mutation 不會讓某筆購買或轉帳被重複處理。完整的錯誤目錄請參閱錯誤。