> ## 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 키마다 보낼 수 있는 요청 수를 제한합니다. 하나의 통합이 모든 사용자의 API 속도를 떨어뜨리지 않도록 하기 위해서입니다.

## 한도

| 한도 | 값 |
| - | - |
| API 키당 요청 수 | 분당 600개 |

한도는 1분 단위의 슬라이딩 윈도로 계산되며 모든 엔드포인트에 합산하여 적용됩니다. [상태 확인](https://docs.getqr.com/ko/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` 헤더를 붙인 경우에만 재시도하세요. 그러면 재시도로 두 번째 QR 코드가 만들어지지 않습니다. [멱등성](https://docs.getqr.com/ko/api/introduction.md#멱등성)을 참조하세요.

## 한도 안에서 사용하기

* `X-RateLimit-Remaining`을 확인하고 0에 도달하기 전에 속도를 줄이세요.
* QR 코드마다 요청을 하나씩 보내는 대신 [QR 코드 대량 생성](https://docs.getqr.com/ko/api/endpoints/bulk-qr-creations.md)을 사용하세요.
* `pageSize=100`으로 페이지당 최대 100개의 결과를 가져오세요. [페이지네이션](https://docs.getqr.com/ko/api/introduction.md#페이지네이션)을 참조하세요.
* QR 이미지를 캐시하세요. 다운로드는 `ETag`를 반환하므로 `If-None-Match`를 보내면 변경 사항이 없을 때 `304 Not Modified`를 받습니다.

## 다음 단계

> [card] [오류](https://docs.getqr.com/ko/api/errors.md)

> [card] [QR 코드](https://docs.getqr.com/ko/api/endpoints/qr-codes.md)


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