> ## Documentation Index
> Fetch the complete documentation index at: https://supertone-b89202c8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 요청 수 제한

> 계정 티어별 분당 요청 제한과 제한 초과 시 대응 방법을 안내합니다.

> [!NOTE]
>
> 이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 [영어 원문](/en/docs/production/rate-limits)을 함께 확인해 주세요.

Supertone API는 안정적인 서비스 운영을 위해 요청 수 제한 정책을 운영합니다. 제한은 플랜에 따라 확장되며, 더 높은 처리량이 필요한 경우 [엔터프라이즈 플랜](https://docs.google.com/forms/d/1YexQpjpK0ZEou12blTytkZLqvrV-Uv95GbhxoOQ54R8/edit)을 이용하실 수 있습니다.

## 티어별 제한

### 음성 생성 (`text_to_speech`, `stream_speech`)

| Tier | Requests per minute |
| - | :-: |
| Free & Starter | **20** |
| Creator | **30** |
| Pro | **60** |
| Enterprise | Custom |

### 보이스 클로닝 (`create_cloned_voice`)

| Tier | Requests per minute |
| - | :-: |
| Starter, Creator, Pro | **10** |
| Free | Not available |
| Enterprise | Custom |

그 외 엔드포인트(보이스 목록 조회, 사용량 조회, 크레딧 잔액 조회, predict-duration)는 음성 생성 제한의 대상이 아니지만, 남용 시에는 일시적으로 제한될 수 있습니다.

## 제한을 초과한 경우

API는 다음과 같이 응답합니다.

```
HTTP/1.1 429 Too Many Requests
```

경우에 따라 서버가 일시적으로 요청을 지연시키거나 드롭하여 트래픽 급증을 흡수할 수 있습니다. `429` 응답은 잠시 대기 후 재시도해야 한다는 신호로 처리해 주세요. 자세한 내용은 [재시도와 백오프](/ko/docs/production/retries-and-backoff)를 참고하시기 바랍니다.

## 코드에서 요청 제한 처리하기

**Python**

```python theme={"dark"}
from supertone import Supertone, errors

try:
    response = client.text_to_speech.create_speech(...)
except errors.TooManyRequestsErrorResponse as e:
    # Retry after a backoff — see the retries-and-backoff guide
    wait_then_retry()
```

**TypeScript**

```typescript theme={"dark"}
import * as errors from "@supertone/supertone/models/errors";

try {
  const response = await client.textToSpeech.createSpeech({ /* ... */ });
} catch (err) {
  if (err instanceof errors.TooManyRequestsErrorResponse) {
    // Retry after a backoff
    await waitThenRetry();
  } else {
    throw err;
  }
}
```

두 SDK 모두 `retry_config` / `retryConfig` 옵션을 통해 `429`(및 일시적인 `5xx`) 응답에 대해 지수 백오프 방식으로 자동 재시도를 수행합니다. 권장 설정은 [재시도와 백오프](/ko/docs/production/retries-and-backoff)를 참고해 주세요.

## 제한을 고려한 설계

* **상위 단계에서 묶어 보내기.** 하나의 사용자 동작이 여러 문장을 생성하는 경우(예: 문단 번역), 한 번에 모두 호출하지 말고 큐를 거쳐 순차 처리하세요.
* **엣지에서 스로틀링.** 사용자별 자체 제한을 적용해, 단일 사용자의 폭주가 계정 전체 분당 한도를 소모하지 않도록 하세요.
* **장문 자동 청크 처리.** 2,000자 단위의 한 번의 호출이 내부적으로는 약 7회의 API 호출로 분할됩니다. 분당 예산을 산정할 때 이를 고려해야 합니다.
* **스트리밍 챗봇.** 문장 단위 스트리밍 TTS는 문장당 한 번의 API 호출을 사용합니다. 여러 문단으로 구성된 응답은 Free 티어 한도를 몇 초 만에 소진할 수 있습니다.

## 더 높은 제한이 필요하신가요?

지속적으로 제한에 도달하거나 고트래픽 서비스를 운영 중이라면, 맞춤형 제한, 전용 처리 용량, 계정 단위 지원을 제공하는 엔터프라이즈 플랜에 대해 문의해 주세요.

> **[엔터프라이즈 문의](https://docs.google.com/forms/d/1YexQpjpK0ZEou12blTytkZLqvrV-Uv95GbhxoOQ54R8/edit)**
>
> 사용 사례와 트래픽 형태를 알려주시면 적합한 옵션으로 회신드립니다.


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