> ## 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.

# 오류 처리

> Supertone API가 반환하는 HTTP 상태 코드와 원인, 그리고 프로덕션 코드에서의 올바른 대응 방법을 안내합니다.

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

Supertone API는 표준 HTTP 상태 코드를 사용합니다. 오류 발생 시 문제를 설명하는 JSON 본문이 반환되며, SDK는 이를 타입이 지정된 예외로 노출하므로 손쉽게 캐치하여 처리할 수 있습니다.

## 상태 코드 레퍼런스

| Status | 의미 | 가장 흔한 원인 |
| - | - | - |
| `200 OK` | 성공 | — |
| `400 Bad Request` | 잘못된 형식의 요청 | 필수 필드 누락, 잘못된 enum 값, `text` 300자 초과(raw API에 한함), `voice_settings` 값이 허용 범위를 벗어남. |
| `401 Unauthorized` | 인증 실패 | `x-sup-api-key`가 누락되었거나 올바르지 않음. |
| `402 Payment Required` | 크레딧 부족 | 크레딧 잔액이 0이거나 요청을 처리하기에 부족함. |
| `403 Forbidden` | 권한 없음 | 다른 계정 소유의 커스텀 보이스를 호출하거나, 권한이 없는 키를 사용한 경우. |
| `404 Not Found` | 리소스 없음 | 잘못된 `voice_id`, 엔드포인트 경로 오타. |
| `408 Request Timeout` | 서버가 시간 내에 처리하지 못함 | 일시적인 문제 — 재시도해 주세요. |
| `413 Payload Too Large` | 업로드 용량 초과 | 보이스 클로닝 오디오가 3 MB를 초과함. |
| `415 Unsupported Media Type` | 잘못된 업로드 포맷 | 보이스 클로닝 오디오가 WAV/MP3 형식이 아님. |
| `429 Too Many Requests` | 요청 수 제한 도달 | [요청 수 제한](/ko/docs/production/rate-limits)을 참고해 주세요. |
| `500 Internal Server Error` | 서버 측 문제 | 보통 일시적 — 백오프와 함께 재시도해 주세요. |

## SDK 오류 클래스

두 SDK 모두 각 상태 코드를 타입이 지정된 오류 클래스로 매핑합니다. 문자열을 파싱하는 것보다 특정 클래스를 캐치하는 방식이 더 명확합니다.

**Python**

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

try:
    response = client.text_to_speech.create_speech(...)
except errors.BadRequestErrorResponse as e:
    # 400 — fix the request
    log.error("Bad request: %s", e.message)
except errors.UnauthorizedErrorResponse:
    # 401 — re-check the API key
    rotate_key_and_retry()
except errors.PaymentRequiredErrorResponse:
    # 402 — alert the user / billing system
    notify_low_credits()
except errors.ForbiddenErrorResponse:
    # 403 — wrong voice for this account
    fallback_to_preset_voice()
except errors.TooManyRequestsErrorResponse:
    # 429 — back off and retry
    backoff_and_retry()
except errors.InternalServerErrorResponse:
    # 500 — retry transient failure
    retry_with_backoff()
except errors.SupertoneError as e:
    # Any other API-level error
    log.exception("Supertone API error: %s", e.message)
```

**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.BadRequestErrorResponse) {
    console.error("Bad request:", err.message);
  } else if (err instanceof errors.UnauthorizedErrorResponse) {
    rotateKeyAndRetry();
  } else if (err instanceof errors.PaymentRequiredErrorResponse) {
    notifyLowCredits();
  } else if (err instanceof errors.ForbiddenErrorResponse) {
    fallbackToPresetVoice();
  } else if (err instanceof errors.TooManyRequestsErrorResponse) {
    await backoffAndRetry();
  } else if (err instanceof errors.InternalServerErrorResponse) {
    await retryWithBackoff();
  } else if (err instanceof errors.SupertoneError) {
    console.error(`HTTP ${err.statusCode}: ${err.message}`);
  } else {
    throw err;
  }
}
```

모든 SDK 오류는 다음 속성을 노출합니다.

| Property | 설명 |
| - | - |
| `message` | 서버에서 제공하는 오류 메시지입니다. |
| `status_code` / `statusCode` | HTTP 상태 코드입니다. |
| `headers` | 응답 헤더입니다. |
| `body` | 응답 본문의 원본 문자열입니다. |
| `raw_response` / `rawResponse` | 내부 HTTP 응답 객체입니다. |

## 오류별 대응 방법

### 4xx — 클라이언트 측

| Code | 권장 대응 |
| - | - |
| `400` | 재시도하지 마세요 — 요청 본문을 로그로 남기고 스키마 불일치를 수정합니다. |
| `401` | 키 값, 콘솔에서의 키 활성화 상태, 그리고 프록시에 의해 `x-sup-api-key` 헤더가 제거되지 않았는지 확인하세요. |
| `402` | 사용자에게 "크레딧 부족" 메시지를 노출하고 결제 페이지로 안내한 뒤 워크플로를 중단하세요. 크레딧을 충전하지 않고 재시도하면 동일하게 실패합니다. |
| `403` | 해당 보이스가 이 계정 소유인지 확인하세요. 커스텀 보이스는 계정 단위로 범위가 제한됩니다. |
| `404` | `GET /v1/voices` 또는 `GET /v1/custom-voices`를 호출해 `voice_id`가 실제로 존재하는지 확인하세요. |
| `413` | 업로드 용량을 줄여 주세요 — 모노로 재인코딩하거나, 비트레이트를 낮추거나, 3 MB 미만으로 잘라 주세요. |
| `415` | 업로드 파일을 WAV 또는 MP3로 재인코딩하세요. |
| `429` | [재시도와 백오프](/ko/docs/production/retries-and-backoff)를 참고해 주세요. |

### 5xx — 서버 측

| Code | 권장 대응 |
| - | - |
| `408` | 재시도해 주세요 — 보통 일시적 문제입니다. |
| `500` | 지수 백오프와 함께 재시도해 주세요. 5분 이상 지속될 경우 [고객 지원](/ko/docs/resources/support)에 문의해 주세요. |

## 자주 발생하는 케이스

* POST 요청에 **`Content-Type: application/json` 누락** 시 `400` 발생.
* 복사/붙여넣기 과정에서 흔히 발생하는 **API Key의 앞뒤 공백**으로 인해 `401` 발생.
* 다른 계정의 **커스텀 보이스 호출** 시, ID를 "알고 있다"고 해도 `403` 발생.
* raw API에 **`text`를 300자 초과**로 전송 시 `400` 발생. 더 긴 텍스트는 SDK를 사용해 자동 청크 분할하세요.

## 관련 문서

> **[재시도와 백오프](/ko/docs/production/retries-and-backoff)**
>
> `429`와 `5xx`에 대한 올바른 재시도 정책을 확인하세요.

> **[요청 수 제한](/ko/docs/production/rate-limits)**
>
> 계정 티어별 제한을 확인하세요.


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