> ## 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]
>
> 경로 버전은 리소스마다 다릅니다. 한도는 버전과 무관하게 동일하게 적용됩니다. [버전과 호환성](https://docs.trychainshift.ai/guides/versioning.md)을 참고하세요.

## 한도

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

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

## 응답 헤더

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` 헤더에 담긴 초만큼 기다린 뒤 다시 요청하세요.

## 한도에 맞춰 요청하기

**1. 남은 요청 수 확인**

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

**2. 429 응답 처리**

`429` 응답을 받으면 `Retry-After` 헤더의 초만큼 대기한 뒤 재시도합니다.

**3. 대량 작업은 분산**

많은 요청을 보내야 한다면 초당 한도에 맞춰 간격을 두고 나눠 보냅니다.

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

과금은 [크레딧](https://docs.trychainshift.ai/guides/credits.md)을 참고하세요.


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