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

# Rate Limit & 크레딧

> 조직 단위 요청 한도와 크레딧 과금 모델, 초과 시 처리 방법

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

## 한도

| 항목    | 값                             |
| ----- | ----------------------------- |
| 기본 한도 | 초당 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>

## 크레딧

과금 대상 엔드포인트는 조직 크레딧을 차감합니다. 프롬프트 실행은 총 실행 수(프롬프트 수 × 모델 수 × `repeatCount`)에 모델별 단가를 곱한 만큼 과금되며, **수집이 완료된 실행 건마다** 차감됩니다(후차감). 실패한 실행은 차감되지 않습니다.

현재 지원하는 8개 모델은 모두 실행 1건당 **1크레딧**이므로, 예상 크레딧은 총 실행 수와 같습니다.

```
프롬프트 20개 × 모델 4개 × repeatCount 5 = 400 실행 = 400 크레딧
```

<Note>
  최신 모델별 단가와 크레딧 요금은 [플랫폼 요금 안내](https://platform.trychainshift.ai)에서 확인하세요.
</Note>

* 잔액이 없으면 제출이 거부되고 `402`(`INSUFFICIENT_CREDITS`)가 반환됩니다.
* 잔액이 총 필요량보다 적으면 제출은 성공하지만, 진행 중 잔액이 소진되면 남은 수집 건이 실패 처리됩니다.
* 잔액은 `GET /credits/me`로 조회하며, 이 호출 자체는 크레딧을 소비하지 않습니다.

```bash theme={null}
curl -H "API-Key: YOUR_API_KEY" \
  "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/credits/me"
```

```json theme={null}
{ "balance": 1250.5 }
```

`balance`는 남은 크레딧 수입니다. 위 잔액이면 400 실행짜리 요청을 3회 제출할 수 있습니다.

<Tip>
  대량 실행을 요청하기 전에 `GET /credits/me`로 잔액을 확인하세요. 잔액이 예상 과금량보다 적으면 수집이 중간에 실패할 수 있습니다.
</Tip>

## MCP 사용 시

MCP 서버 엔드포인트(`/mcp`) 자체에는 조직 단위 한도가 직접 적용되지 않습니다. 다만 MCP tool이 내부적으로 호출하는 Platform API에는 동일한 한도가 적용되므로, tool을 통한 요청도 조직 한도를 함께 소비합니다.