メインコンテンツまでスキップ

APIクォータガイド

カフェ24 APIは安定したサービス運用のために呼び出し量を制限しています。 制限は総量制御と流量制御の2階層で同時に動作し、いずれかを超過すると 429 Too Many Requests レスポンスが返されます。

📚 目次​

🧭 クォータの2階層構造​

2つの制限は防ぐ対象が異なります。総量は一定時間に使える全体量を、流量は瞬間的な集中を制御します。

      ① 総量制御（クォータ）                 ② 流量制御（リーキーバケット）
   ┌──────────────────────────┐         ┌──────────────────────────┐
   │  10分単位で集計           │         │  バケット容量 40          │
   │   ・呼び出し回数 3,000回  │         │  1秒あたり2ずつ減少       │
   │   ・呼び出し時間 600秒    │         │                          │
   │                          │         │  瞬間的な集中を遮断       │
   │  長時間の累積使用量を制御 │         │                          │
   └──────────────────────────┘         └──────────────────────────┘
              │                                      │
              └──────────────┬───────────────────────┘
                             ▼
                超過時 429 Too Many Requests
区分① 総量制御② 流量制御
集計単位10分リアルタイム（秒単位）
制限対象呼び出し回数・呼び出し時間連続呼び出しの速度
防ぐ状況一日を通して過剰に使い続ける場合短時間にまとめて呼び出す場合
確認方法超過時の429レスポンスX-Api-Call-Limit レスポンスヘッダー
ヒント

2つの制限は独立しています。秒間の呼び出し速度を十分に落としても10分の総量を超えれば429が発生し、逆に総量に余裕があっても瞬間的にまとめて呼び出せば429が発生します。

📊 既定のクォータ​

別途設定しない限り、以下の値が既定で適用されます。

項目既定値説明
呼び出し回数10分あたり3,000回10分間に許可されるAPIリクエスト総数
呼び出し時間10分あたり600秒10分間にAPI処理へ使用できる累積時間

呼び出し時間とは​

レスポンスの遅いAPIを繰り返し呼び出すと、呼び出し回数に余裕があっても呼び出し時間が先に尽きることがあります。

例）平均応答1秒のAPIを10分間に600回呼び出した場合
    呼び出し回数: 600 / 3,000  → 余裕あり
    呼び出し時間: 600 / 600秒  → 枯渇 ⚠️  以降のリクエストは429

大量照会の際は、重いAPIを繰り返し呼び出すより limit パラメーターでページサイズを大きくし、呼び出し回数そのものを減らす方がクォータ消費に有利です。 照会パラメーターの詳しい使い方はGET API利用ガイドを参照してください。

備考

ショッピングモールごとに個別のクォータが設定されている場合は、上記の既定値ではなくその設定が適用されます。

🪣 瞬間的な流量制限​

総量とは別に、瞬間的な呼び出しの集中は**リーキーバケット（漏れバケツ）**方式で制御されます。

動作方式​

   リクエスト1件 = 水1滴
        │
        ▼
   ┌─────────┐
   │ ▓▓▓▓▓▓▓ │  バケット容量: 40
   │ ▓▓▓▓▓▓▓ │  → 満杯になると429
   └────┬────┘
        │  1秒あたり2ずつ自動減少
        ▼
項目値意味
バケット容量40瞬間的に溜められる最大リクエスト数
減少速度1秒あたり2回1秒ごとにバケットから2件ずつ抜ける

実務上の基準​

  • 秒間2回以下で呼び出せばバケットが溜まらず、制限を受けません。
  • 一時的に秒間2回を超えても、バケット容量（40）の範囲内であれば短い集中は許容されます。
  • 継続的に秒間2回を超えるとバケットが満杯になり429が発生します。

📮 X-Api-Call-Limitヘッダー​

すべてのAPIレスポンスには現在のバケット状態がヘッダーとして含まれます。

X-Api-Call-Limit: 1/40
                  │  │
                  │  └─ バケット容量
                  └──── 現在の使用量

確認例​

curl -i -X GET \
  'https://yourmall.cafe24api.com/api/v2/admin/products' \
  -H 'Authorization: Bearer {access_token}'

# レスポンスヘッダー
# HTTP/1.1 200 OK
# X-Api-Call-Limit: 1/40

Node.js​

const response = await axios.get(url, { headers });

const callLimit = response.headers['x-api-call-limit'];  // "1/40"
const [used, capacity] = callLimit.split('/').map(Number);

// バケットが80%以上埋まったら呼び出し速度を落とす
if (used / capacity > 0.8) {
  await new Promise(resolve => setTimeout(resolve, 1000));
}

Python​

response = requests.get(url, headers=headers)

call_limit = response.headers.get('X-Api-Call-Limit')  # "1/40"
used, capacity = map(int, call_limit.split('/'))

# バケットが80%以上埋まったら呼び出し速度を落とす
if used / capacity > 0.8:
    time.sleep(1)
ヒント

429が発生してから対処するより、このヘッダーを継続的に確認してあらかじめ速度を調整する方が安定します。

🔀 APIごとの違い​

API総量クォータ流量制限備考
Admin API10分 3,000回／600秒バケット40、1秒あたり2減少Access Token単位で集計
Front API（Basic認証）既定のクォータを適用バケット40、1秒あたり2減少認証済みリクエストとして扱われる
Front API（非認証）低い上限を適用低い上限を適用Basic認証の利用を推奨
D.Collection API—IPあたり1分間に最大40回別途ポリシーを適用

Front APIは認証の有無によって呼び出し制限が異なります。 client_id のみを渡す非認証方式は制限が低く適用されるため、サービス運用時はBasic認証方式を使用してください。 認証方法はOAuth 2.0認証ガイドを参照してください。

🐛 429への対処方法​

レスポンス形式​

HTTP/1.1 429 Too Many Requests
X-Api-Call-Limit: 40/40

指数バックオフによるリトライ​

429を受け取った場合は即座に再試行せず、待機時間を徐々に伸ばしながらリトライします。

Node.js​

async function requestWithRetry(config, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await axios(config);
    } catch (error) {
      if (error.response?.status !== 429) {
        throw error;
      }

      // 1秒 → 2秒 → 4秒 → 8秒 → 16秒
      const waitMs = Math.pow(2, attempt) * 1000;
      console.warn(`429が発生、${waitMs}ms後にリトライ (${attempt + 1}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, waitMs));
    }
  }

  throw new Error('リトライ回数の上限を超えました');
}

Python​

import time

def request_with_retry(method, url, headers, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        response = requests.request(method, url, headers=headers, **kwargs)

        if response.status_code != 429:
            return response

        # 1秒 → 2秒 → 4秒 → 8秒 → 16秒
        wait_sec = 2 ** attempt
        print(f'429が発生、{wait_sec}秒後にリトライ ({attempt + 1}/{max_retries})')
        time.sleep(wait_sec)

    raise Exception('リトライ回数の上限を超えました')

大量処理時の推奨パターン​

状況推奨方法
全件リストの収集limit を最大にして呼び出し回数を減らし、ページ間に間隔を置く
多件の登録・修正並列呼び出しではなく逐次呼び出し＋リクエスト間に最低0.5秒の間隔
バッチ処理業務時間帯を避けて分散実行
リアルタイム連携date 系パラメーターで範囲を絞り差分のみ照会
警告

リトライ処理を入れずに失敗したリクエストを即座に繰り返すと、バケットが満杯のまま維持され正常なリクエストまで遮断されます。必ず待機時間を置いてリトライしてください。

📚 関連ドキュメント​