> ## 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 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

GetQR API 会限制每个 API 密钥可以发送的请求数，以免单个集成拖慢所有人的 API 访问速度。

## 限制

| 限制 | 值 |
| - | - |
| 每个 API 密钥的请求数 | 每分钟 600 个 |

该限制按一分钟的滑动窗口计算，并对所有端点合并生效。[健康检查](https://docs.getqr.com/zh/api/endpoints/health.md)无需密钥，也不计入限制。

## 速率限制响应头

使用有效 API 密钥的请求，其响应（包括错误响应）都会带有以下响应头：

| 响应头 | 说明 |
| - | - |
| `X-RateLimit-Limit` | 每个窗口允许的最大请求数。 |
| `X-RateLimit-Remaining` | 当前窗口内剩余的请求数。 |
| `X-RateLimit-Reset` | 窗口重置的时间，为以毫秒为单位的 Unix 时间戳。 |
| `Retry-After` | 距离窗口重置的秒数（向上取整）。请等待这段时间后再重试。 |

## 超出限制时

超出限制后，API 会返回 `429`，附带 `rate_limit_exceeded` 代码和相同的响应头：

```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` 请求头。这样重试就不会创建第二个二维码。请参阅[幂等性](https://docs.getqr.com/zh/api/introduction.md#幂等性)。

## 避免超出限制

* 关注 `X-RateLimit-Remaining`，在它降到 0 之前放慢请求速度。
* 使用[批量创建二维码](https://docs.getqr.com/zh/api/endpoints/bulk-qr-creations.md)，而不是为每个二维码单独发送一个请求。
* 使用 `pageSize=100` 每页获取最多 100 条结果。请参阅[分页](https://docs.getqr.com/zh/api/introduction.md#分页)。
* 缓存二维码图片：下载接口会返回 `ETag`，您可以发送 `If-None-Match`，在内容未变化时获得 `304 Not Modified`。

## 后续步骤

> [card] [错误](https://docs.getqr.com/zh/api/errors.md)

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)


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