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

# 요청 수 제한

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

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

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)를 참고하시기 바랍니다.

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

<Tabs>
  <Tab title="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()
    ```
  </Tab>

  <Tab title="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;
      }
    }
    ```
  </Tab>
</Tabs>

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

## 제한을 고려한 설계

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

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

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

<Card title="엔터프라이즈 문의" icon="building" href="https://docs.google.com/forms/d/1YexQpjpK0ZEou12blTytkZLqvrV-Uv95GbhxoOQ54R8/edit">
  사용 사례와 트래픽 형태를 알려주시면 적합한 옵션으로 회신드립니다.
</Card>