レート制限とスロットリング

API レート制限 429 スロットリング

この記事の対象
レシートローラーAPIを大量に呼び出すバッチ処理・同期処理を実装する開発者向けです。

レート制限の単位

レート制限はアプリ × 店舗の組み合わせ単位で適用されます。同じアプリでも店舗が異なれば別カウントです。

プラン別の上限（店舗側プラン）

プラン	秒間	日次
スターター	10 req/s	100,000 req
グロース	50 req/s	1,000,000 req
エンタープライズ	個別契約	個別契約

短時間のバーストは 2倍 までトークンバケット方式で許容されます。

レスポンスヘッダー

すべてのAPIレスポンスに、現在のレート制限状況が含まれます。

X-RateLimit-Limit: 10           ← 1秒あたりの上限
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. バッチエンドポイントを使う

レシートローラーは複数リソースを1リクエストで扱えるバッチAPIを提供しています。1件ずつ呼び出すよりレート制限的に有利です。

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

3. キャッシュ・差分取得

変更されにくいデータ（店舗情報・商品マスター）はクライアント側でキャッシュ
一覧取得は updated_after で差分のみ取得
Webhookで通知を受けてからAPIで詳細取得（ポーリング全廃）

4. 並行度の制御

並列リクエスト数は秒間上限以下に抑えます。Promise.all で全件並列起動するとあっという間に429。同時実行数を p-limit 等で制御してください。

制限緩和の相談

業務特性上どうしても上限を超える場合は、エンタープライズプランの個別契約で緩和可能です。営業窓口またはサポートへご相談ください。