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

# レート制限

> 送信できるリクエスト数と、429 レスポンスの扱い方。

> [!NOTE]
>
> GetQR API はベータ版で、一部のワークスペースでのみご利用いただけます。正式リリースまでに内容が変更される場合があります。

GetQR API は、API キーごとに送信できるリクエスト数を制限しています。1 つの連携が API 全体を遅くしないようにするためです。

## 制限

| 制限 | 値 |
| - | - |
| API キーあたりのリクエスト数 | 1 分あたり 600 件 |

制限は 1 分間のスライディングウィンドウで数えられ、すべてのエンドポイントを合わせて適用されます。[ヘルスチェック](https://docs.getqr.com/ja/api/endpoints/health.md) はキーが不要で、カウントもされません。

## レート制限ヘッダー

有効な API キーを使ったリクエストへのレスポンスには、エラーレスポンスも含めて次のヘッダーが付きます。

| ヘッダー | 説明 |
| - | - |
| `X-RateLimit-Limit` | ウィンドウあたりの最大リクエスト数。 |
| `X-RateLimit-Remaining` | 現在のウィンドウで残っているリクエスト数。 |
| `X-RateLimit-Reset` | ウィンドウがリセットされる時刻。ミリ秒単位の Unix タイムスタンプです。 |
| `Retry-After` | ウィンドウがリセットされるまでの秒数（切り上げ）。再試行の前に、この時間だけ待ってください。 |

## 制限を超えた場合

制限を超えると、API は `rate_limit_exceeded` コードと同じヘッダーを付けて `429` を返します。

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792764060000
Retry-After: 37

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "doc_url": "https://getqr.com/account/api-docs#error-rate_limit_exceeded"
  }
}
```

リセット時刻まで待ってから、次のリクエストを送ってください。複数のワーカーが同時に再試行しないようにジッターを加え、`5xx` エラーでは指数バックオフを使います。

```javascript theme={null}
async function getqrFetch(url, options = {}, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, {
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.GETQR_API_KEY}`,
        ...options.headers,
      },
    });

    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= maxRetries) return res;

    // On 429, wait for Retry-After (seconds). Otherwise back off: 1s, 2s, 4s…
    const retryAfter = Number(res.headers.get("Retry-After"));
    const wait =
      res.status === 429 && retryAfter > 0
        ? retryAfter * 1000
        : 1000 * 2 ** attempt;
    const jitter = Math.random() * 250;

    await new Promise((r) => setTimeout(r, wait + jitter));
  }
}
```

> [!TIP]
>
> `POST /api/v1/qrs` を再試行するのは、`Idempotency-Key` ヘッダーを付けた場合だけにしてください。そうすれば、再試行で 2 つ目の QR コードが作成されることはありません。[冪等性](https://docs.getqr.com/ja/api/introduction.md#冪等性) をご覧ください。

## 制限内に収める

* `X-RateLimit-Remaining` を監視し、0 になる前にペースを落とします。
* QR コードごとに 1 リクエストを送る代わりに、[QR コードの一括作成](https://docs.getqr.com/ja/api/endpoints/bulk-qr-creations.md) を使います。
* `pageSize=100` で 1 ページあたり最大 100 件を取得します。[ページネーション](https://docs.getqr.com/ja/api/introduction.md#ページネーション) をご覧ください。
* QR コードの画像をキャッシュします。ダウンロードは `ETag` を返すので、`If-None-Match` を送れば、変更がないときに `304 Not Modified` を受け取れます。

## 次のステップ

> [card] [エラー](https://docs.getqr.com/ja/api/errors.md)

> [card] [QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.