# 레이트 리밋

> 조직 단위 RPM/TPM 한도, 429 동작, 재시도 가이드를 설명합니다.

Source: https://kiln.bricksum.com/docs/ko/rate-limits

레이트 리밋은 조직 단위로 적용됩니다. 현재 기본값은 다음과 같습니다.

- **요청**: 기본값은 조직당 60 RPM(분당 요청 수)입니다. 초과하면 429가 반환됩니다.
- **토큰**: TPM(분당 토큰 수)은 기본 무제한이며, 운영팀이 조직별 한도를 설정할 수 있습니다. 초과하면 429가 반환됩니다.
- **동시성**: 조직당 동시 요청은 8건입니다. 8건이 처리 중일 때 들어온 요청은 모델에 도달하기 전에 즉시 429로 거부됩니다.

참고

조직의 현재 한도는 콘솔의 조직 → 개요에서 확인할 수 있습니다. 위 기본값은 서비스가 발전하면서 바뀔 수 있으며, 부하 테스트 등으로 더 높은 한도가 필요하면 실행 전에 문의하세요.

## 한도 초과 시

한도를 초과하면 `429 Too Many Requests` 상태가 반환됩니다. 분당 요청 또는 분당 토큰 429에는 `x-ratelimit-reset` 헤더가 실립니다. 값은 현재 1분 윈도우가 리셋될 때까지 남은 초입니다. 나머지 헤더는 한도 종류에 따라 다릅니다. 분당 요청 429에는 x-ratelimit-limit과 x-ratelimit-remaining이, 분당 토큰 429에는 x-ratelimit-limit-tokens와 x-ratelimit-remaining-tokens가 함께 실립니다. 동시성 429는 이후 단계에서 반환되며 이 헤더가 하나도 없으므로 지수 백오프로 재시도하세요.

## 재시도 가이드

- 429와 5xx 응답은 재시도하세요. 400/401/403 같은 4xx는 재시도하지 마세요.
- 지터를 포함한 지수 백오프를 사용하세요(예: 1s, 2s, 4s, ... 상한 적용).
- 분당 요청 또는 분당 토큰 429에서는 지연 시간을 추측하지 말고 x-ratelimit-reset 초만큼 기다리세요. 동시성 429에는 이 헤더가 없으므로 지수 백오프를 사용하세요.
- 총 재시도 횟수를 제한하고(예: 5회) 사용자에게 명확한 에러를 표시하세요.

상태 코드로 분기하고, 응답에 x-ratelimit-reset이 있으면 그 값을 읽는 재시도 루프입니다. 동시성 429와 5xx에는 리셋 헤더가 없으므로 지수 백오프를 사용합니다.

**Python**
```python
import random
import time

def post_with_retry(client, path, payload, max_attempts=5):
    for attempt in range(max_attempts):
        r = client.post(path, json=payload)
        if r.status_code < 400:
            return r
        # 400, 401, 402, 403, 404 and 405 describe the request. Fix it instead.
        if r.status_code != 429 and r.status_code < 500:
            r.raise_for_status()
        reset = r.headers.get("x-ratelimit-reset")
        if reset is not None:
            delay = float(reset)          # requests/min or tokens/min limit
        else:
            delay = min(2 ** attempt, 30) # concurrency 429 and 5xx: no reset header
        time.sleep(delay + random.uniform(0, 1))
    r.raise_for_status()
```

## 크레딧 소진

크레딧 잔액이 0이 되면 요청이 차단되고 `402 Payment Required` 상태가 반환됩니다. 잔액은 [크레딧 페이지](https://kiln.bricksum.com/app/credits)에서 확인하세요.

전체 상태 코드 목록은 [에러](https://kiln.bricksum.com/docs/ko/errors) 페이지를 참고하세요.