Shopify API レートリミット制限 (429エラー) の原因と自動リトライ設計

大量の在庫同期バッチ実行時や、フラッシュセール時に注文データを一括取得しようとした際に発生。

エラー根本原因 & クイック解決サマリー

2026年最新API仕様

レスポンスヘッダー『Retry-After』を参照し、指定された秒数だけ処理を非同期待機（Sleep）させる。

指数バックオフ（Exponential Backoff with Jitter）を用いた自動リトライロジックを実装する。

REST APIからGraphQL Admin APIへ移行し、Bulk Operations APIを用いて大量データを一括処理する。

📋 主要スペック & 決定ファクトシート

エラーコード: HTTP 429
重要度レベル: 高 (HIGH)
推奨解決コード: TYPESCRIPT

根本原因（Root Cause）

Shopify REST API（40リクエスト/秒のリーキーバケット）または GraphQL Admin API（計算コスト上限）を超過したためサーバーから一時的にリクエストが遮断されている。

放置した場合のビジネス影響

在庫同期が中断し、実店舗や他モールとの『売り違い（欠品キャンセル）』や注文情報の取りこぼしが発生します。

推奨解決コード実装例（TYPESCRIPT）

Retry-Afterヘッダーを最優先し、ランダムなJitterを加えることで複数スレッドの同時再衝突を防ぎます。

❌ アンチパターン（エラーが発生する実装）

// ❌ 単純なループで全件連続リクエスト（即座に429エラーが発生）
for (const item of items) {
  await fetch(`/admin/api/2026-01/inventory_levels/set.json`, { ... });
}

✔ 正しい修正コード（推奨実装）

//  指数バックオフ付き自動リトライ関数
async function fetchWithRetry(url: string, options: RequestInit, retries = 5, delay = 1000): Promise<Response> {
  try {
    const res = await fetch(url, options);
    if (res.status === 429 && retries > 0) {
      const retryAfter = Number(res.headers.get("Retry-After")) || (delay / 1000);
      const waitTime = (retryAfter * 1000) + Math.random() * 500; // Jitter
      console.warn(`[Rate Limited] Waiting ${waitTime}ms before retry. Retries left: ${retries}`);
      await new Promise((resolve) => setTimeout(resolve, waitTime));
      return fetchWithRetry(url, options, retries - 1, delay * 2);
    }
    return res;
  } catch (err) {
    if (retries <= 0) throw err;
    await new Promise((resolve) => setTimeout(resolve, delay));
    return fetchWithRetry(url, options, retries - 1, delay * 2);
  }
}