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

# API 使用指南

> 了解 QFPay API 請求頻率限制與最佳實務建議。

為確保平台穩定性與所有商戶的公平使用權益，QFPay 對 API 請求實施頻率限制（Rate Limiting）政策。

本頁說明請求限制規則、錯誤回應機制，以及建議的實作方式。

***

## 請求頻率限制

目前限制如下（以商戶為單位計算）：

* **每秒上限**：100 Requests Per Second（RPS）
* **每分鐘上限**：400 Requests Per Minute（RPM）

若超過限制，API 將回應：

```http HTTP theme={null}
HTTP 429 Too Many Requests
```

觸發限制時，該請求將不會被處理。

<Note>
  請求限制以商戶憑證為計算基準，而非單一 IP 位址。
</Note>

***

## 使用建議

為避免觸發限流並確保系統穩定運作，建議採取以下最佳實務：

1. **批次處理請求**\
   若 API 支援批次操作，應優先使用以降低請求次數。
2. **優化查詢條件**\
   合理使用篩選條件與分頁機制，避免高頻輪詢（Polling）。
3. **實作快取機制**\
   對於高重複性查詢（例如支付狀態查詢）應使用短期快取策略。
4. **監控請求頻率**\
   建立監控與日誌機制，追蹤 RPS 與錯誤率，避免突發性流量超標。

***

## 錯誤處理建議

當收到 `HTTP 429` 回應時，建議採取以下處理方式：

### 1. 實作重試機制

* 延遲數秒後再進行重試
* 避免立即重送請求

### 2. 使用指數退避策略（Exponential Backoff）

每次重試時逐步增加等待時間，例如：

* 第一次延遲 1 秒
* 第二次延遲 2 秒
* 第三次延遲 4 秒
* 依序遞增

此策略可降低再次觸發限流的風險。

<Warning>
  請勿在收到 429 後立即大量重試，否則可能導致持續性封鎖或延長限流時間。
</Warning>

***

## 高峰流量管理

若預期流量可能大幅增加（例如促銷活動或大型檔期），請提前聯絡技術支援團隊：

[technical.support@qfpay.com](mailto:technical.support@qfpay.com)

提前通知可協助評估是否需要調整資源配置，以確保服務穩定。

***

## 建議整合流程

1. 建立請求頻率監控
2. 實作重試與退避策略
3. 測試高併發情境
4. 上線前確認峰值流量預估

妥善的流量管理可降低交易失敗與系統風險。