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

# Rate Limit

> 조직 단위 요청 한도와 초과 시 처리 방법

Platform API의 모든 인증 엔드포인트(`/api/v1/platform/*` · `/api/v1beta/platform/*`)에는 조직(organization) 단위 요청 한도가 적용됩니다. 한도는 조직별로 따로 집계되므로, 한 조직의 트래픽이 다른 조직에 영향을 주지 않습니다.

<Note>
  경로 버전은 리소스마다 다릅니다. 한도는 버전과 무관하게 동일하게 적용됩니다. [버전과 호환성](/guides/versioning)을 참고하세요.
</Note>

## 한도

| 항목    | 값                             |
| ----- | ----------------------------- |
| 기본 한도 | 초당 10회                        |
| 집계 단위 | 조직(API 키가 속한 조직)              |
| 적용 범위 | 인증이 필요한 모든 Platform API 엔드포인트 |

<Note>
  한도는 1초 고정 윈도우로 집계됩니다. 매 초가 시작될 때 카운터가 초기화됩니다.
</Note>

## 응답 헤더

Rate Limit이 적용된 모든 응답에는 현재 윈도우의 상태가 헤더로 포함됩니다.

| 헤더                      | 설명                                              |
| ----------------------- | ----------------------------------------------- |
| `X-RateLimit-Limit`     | 윈도우당 허용 요청 수                                    |
| `X-RateLimit-Remaining` | 현재 윈도우에 남은 요청 수                                 |
| `X-RateLimit-Reset`     | 현재 윈도우가 초기화되는 시각 (Unix epoch 초)                 |
| `Retry-After`           | 다시 요청하기까지 기다려야 하는 초. 한도를 초과한 응답(`429`)에만 포함됩니다. |

## 한도 초과 응답

한도를 초과하면 API는 `429 Too Many Requests`와 함께 다음 본문을 반환합니다.

```json theme={null}
{
  "code": "PLATFORM_RATE_LIMIT_EXCEEDED",
  "message": "요청이 너무 많습니다. 잠시 후 다시 시도해주세요."
}
```

이때 `Retry-After` 헤더에 담긴 초만큼 기다린 뒤 다시 요청하세요.

## 한도에 맞춰 요청하기

<Steps>
  <Step title="남은 요청 수 확인">
    응답의 `X-RateLimit-Remaining` 값으로 현재 윈도우에 보낼 수 있는 요청이 얼마나 남았는지 확인합니다.
  </Step>

  <Step title="429 응답 처리">
    `429` 응답을 받으면 `Retry-After` 헤더의 초만큼 대기한 뒤 재시도합니다.
  </Step>

  <Step title="대량 작업은 분산">
    많은 요청을 보내야 한다면 초당 한도에 맞춰 간격을 두고 나눠 보냅니다.
  </Step>
</Steps>

<Tip>
  대량 생성처럼 여러 항목을 한 번에 처리해야 한다면, 항목마다 요청을 보내는 대신 벌크 엔드포인트를 사용해 요청 수를 줄이세요.
</Tip>

과금은 [크레딧](/guides/credits)을 참고하세요.