速率限制與節流

API 速率限制 429 節流

本文的對象
適用於實作大量呼叫 ReceiptRoller API 的批次處理、同步處理的開發者。

速率限制的單位

速率限制以應用程式 × 店鋪的組合為單位套用。即使是同一應用程式，店鋪不同即為不同計數。

各方案的上限（店鋪端方案）

方案	每秒	日度
Starter	10 req/s	100,000 req
Growth	50 req/s	1,000,000 req
Enterprise	個別簽約	個別簽約

短時間的爆量以 2 倍 為上限，透過權杖桶（token bucket）方式允許。

回應標頭

所有 API 回應中都包含目前的速率限制狀況。

X-RateLimit-Limit: 10           ← 每秒的上限
X-RateLimit-Remaining: 7        ← 剩餘
X-RateLimit-Reset: 1745740001   ← 重設時刻（Unix 秒）
X-RateLimit-Resource: receipts  ← 限制的對象

觸及限制時：

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Remaining: 0

{ "error": { "code": "rate_limited", "message": "..." } }

為不觸及限制的實作

1. 用戶端側節流

將限制傳送速率的機制在用戶端也持有。並非等到 429 才處理，而是從一開始就流量控制較穩定。

// 簡易權杖桶範例
class RateLimiter {
  constructor(perSecond) {
    this.tokens = perSecond;
    this.max = perSecond;
    setInterval(() => { this.tokens = this.max; }, 1000);
  }
  async acquire() {
    while (this.tokens <= 0) await sleep(50);
    this.tokens--;
  }
}

2. 使用批次端點

ReceiptRoller 提供可將多個資源以 1 請求處理的批次 API。相較於逐筆呼叫，在速率限制上較有利。

POST /v1/products/batch
{
  "products": [
    { "sku": "A001", "name": "..." },
    { "sku": "A002", "name": "..." }
  ]
}

3. 快取、差分取得

不易變更的資料（店鋪資訊、商品主檔）在用戶端側快取
一覽取得以 updated_after 只取得差分
以 Webhook 接收通知後再以 API 取得詳細（全面廢除輪詢）

4. 並行度的控制

並列請求數控制在每秒上限以下。以 Promise.all 全數並列啟動的話會很快 429。請以 p-limit 等控制同時執行數。

限制緩和的洽詢

若因業務特性怎樣都會超過上限時，可透過 Enterprise 方案的個別簽約緩和。請洽詢營業窗口或支援。