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

# 요청 한도와 429

> API 키의 분당 요청 한도를 정하는 방법, 한도를 세는 방식, 429 응답을 처리하는 방법을 설명합니다.

API 키에는 분당 요청 한도를 정할 수 있습니다. 한도는 키를 발급할 때 '분당 요청 한도'를 적은 키에만 걸리고, 비워 두면 그 키는 한도 없이 씁니다. 한도를 넘은 요청은 `429 rate_limit_exceeded`와 `Retry-After` 헤더를 받습니다.

## 한도를 정해 키 발급하기

키 발급은 콘솔에 로그인한 상태에서만 됩니다. 발급 절차 전체와 키 보관 방법은 [API 키 발급과 첫 호출](https://docs.meterengine.com/authentication/api-keys.md)을 보세요.

**1. 발급 창을 연다**

콘솔 왼쪽 메뉴에서 'API 키와 통보' 화면을 열고 '서버 연동 키' 구역의 'API 키 발급'을 누릅니다.

**2. 분당 요청 한도를 적는다**

'분당 요청 한도'에 1 이상 2,147,483,647 이하의 정수를 적습니다. 비우면 무제한입니다.

**3. 발급한 키의 한도를 확인한다**

키 목록의 '분당 한도' 열에 정한 값이 보입니다. 한도를 정하지 않은 키는 '무제한'으로 표시됩니다.

API 참조의 키 발급 요청(`POST /v1/api-keys`, 콘솔 로그인 전용)에서는 같은 값을 `rate_limit_per_minute`으로 보냅니다. 양수만 받고, 빼거나 `null`로 보내면 무제한입니다.

## 한도를 세는 방식

* **키마다 따로 셉니다.** 키 두 개를 쓰면 한도도 두 개입니다. 같은 키를 여러 연동 서버가 나눠 쓰면 한도를 함께 씁니다.
* **1분 단위로 끊어 세지 않습니다.** 처음에는 한도만큼 연달아 보낼 수 있고, 다 쓴 뒤에는 1분에 한도만큼의 속도로 조금씩 다시 채워집니다. 예를 들어 한도가 60이면 한 번에 60건까지 보낼 수 있고, 그 뒤에는 1초에 1건꼴로 보낼 수 있습니다.
* **키 확인을 통과한 요청은 결과와 관계없이 셉니다.** 400, 403, 404로 끝난 요청도 한 번입니다. 키가 없거나 틀려서 401을 받은 요청은 세지 않습니다.
* **이벤트 배치는 한 요청을 한 번으로 셉니다.** `POST /v1/event-batches`에 이벤트 100건을 담아도 한 번입니다.
* **콘솔 로그인으로 보낸 요청은 세지 않습니다.** 한도는 API 키에만 걸립니다.

> [!NOTE]
>
> 한도는 MeterEngine 서버마다 따로 셉니다. 요청을 여러 서버가 나눠 처리하면 실제 허용량이 정한 값보다 많을 수 있고, 서버가 다시 시작되면 처음부터 다시 셉니다. 한도는 상한을 보장하는 장치가 아니라 연동 쪽 폭주를 막는 장치로 쓰세요.

## 429 응답

한도를 넘으면 아래처럼 응답합니다. `Retry-After`는 다시 보내기 전에 기다릴 초이며 1 이상의 정수입니다.

```http theme={null}
HTTP/2 429
content-type: application/json
retry-after: 1
x-request-id: 5b1e0c7a-2f4d-4b8e-9a63-0d7c1e2f3a45

{"code":"rate_limit_exceeded","message":"요청 한도를 넘었습니다"}
```

429를 받은 요청은 처리되지 않은 것입니다. `Retry-After`만큼 기다렸다가 같은 요청을 그대로 다시 보내면 됩니다.

아래는 이벤트 배치를 보내다 429를 받으면 기다렸다가 다시 보내는 예시입니다.

```bash curl theme={null}
# --retry는 408, 429, 500, 502, 503, 504 응답과 시간 초과에 다시 보냅니다.
# curl 7.66.0 이상은 응답에 Retry-After가 있으면 그만큼 기다립니다.
curl https://meterengine.com/v1/event-batches \
  --retry 5 \
  -H "Authorization: Bearer me_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "transaction_id": "evt_20261105_0001",
        "customer_id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a3c9f10",
        "type": "api_call",
        "properties": { "tokens": 1200 },
        "timestamp": "2026-11-05T10:00:00+09:00"
      }
    ]
  }'
```

```javascript Node (fetch) theme={null}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function sendBatch(events, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const response = await fetch("https://meterengine.com/v1/event-batches", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.METERENGINE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ events }),
    });
    if (response.status !== 429) return response;

    // Retry-After는 초 단위 정수다. 없으면 1초를 기다린다.
    const seconds = Number(response.headers.get("Retry-After") ?? "1");
    await sleep(seconds * 1000);
  }
  throw new Error("요청 한도를 넘어 보내지 못했습니다");
}
```

> [!TIP]
>
> 이벤트가 많으면 단건 요청 대신 배치로 묶어 보내세요. 한 요청에 100건까지 담을 수 있고 한도는 한 번만 씁니다. 배치 응답 읽는 법은 [사용량 이벤트 보내기](https://docs.meterengine.com/integration/events.md)를 보세요.

429를 받는 동안 보내지 못한 이벤트를 쌓아 두었다가 다시 보내는 방법은 [재전송 설계](https://docs.meterengine.com/integration/retries.md)를 보세요.

## 한도 바꾸기

발급한 키의 한도는 바꿀 수 없습니다. 'API 키와 통보' 화면의 '키 권한 변경'은 권한만 바꿉니다. 한도를 바꾸려면 새 한도로 키를 새로 발급하면서 '교체할 기존 키'에 지금 쓰는 키를 고르세요. 기존 키는 교체 유예 시간이 지나면 만료되고, 새 키는 처음부터 새 한도로 셉니다. 교체 절차는 [키 교체, 권한 변경, 폐기](https://docs.meterengine.com/authentication/key-rotation.md)를 보세요.

## 로그인과 가입 신청의 한도

콘솔 로그인과 가입 신청에는 API 키 한도와 별개로 IP와 이메일마다 시도 횟수 한도가 있고, 넘으면 같은 `429 rate_limit_exceeded`와 `Retry-After`를 받습니다. 한도 값은 [가입과 승인](https://docs.meterengine.com/account/signup.md)을 보세요.


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