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

# 오류 코드

> VoiceCheap API에서 반환하는 오류 코드에 대한 전체 참조

# 오류 코드

VoiceCheap API는 표준 HTTP 상태 코드를 사용하며 오류를 원활하게 처리할 수 있도록 구조화된 오류 응답을 반환합니다.

## 오류 응답 형식

모든 오류 응답은 다음 구조를 따릅니다:

```json theme={null}
{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}
```

일부 오류에는 추가 필드가 포함될 수 있습니다. 요청 페이로드 유효성 검사 실패 시
`details`의 잘못된 필드당 하나의 항목을 반환하며, 제약 조건 메시지에 특정 속성이 명시되지 않은 경우 `field`은 생략됩니다:
특정 속성:

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "details": [
    {
      "field": "outputFormat",
      "messages": ["outputFormat must be one of the following values: json, srt, vtt"]
    }
  ]
}
```

## HTTP 상태 코드

| 상태 코드 | 의미 |
| - | - |
| 200 | **OK** - 요청 성공 |
| 400 | **Bad Request** - 잘못된 매개변수 또는 유효성 검사 오류 |
| 401 | **Unauthorized** - 잘못되었거나 누락된 API 키 |
| 403 | **Forbidden** - 유효한 API 키이나 권한 부족 |
| 404 | **Not Found** - 리소스가 존재하지 않음 |
| 409 | **Conflict** - 프로젝트가 요청을 허용하는 상태가 아닙니다 |
| 413 | **Payload Too Large** - 업로드된 파일이 제한을 초과함 |
| 429 | **Too Many Requests** - 속도 제한 초과 |
| 500 | **Internal Server Error** - 서버 측 오류 발생 |
| 502 | **Bad Gateway** - 전사를 완료할 수 없음 |

## 전사 및 전사 내보내기 오류

| 상태 | 코드 | 의미 |
| - | - | - |
| 400 | `INVALID_MEDIA_STREAM` | 업로드된 미디어에 오디오 스트림이 포함되어 있지 않음 |
| 400 | `DURATION_TOO_LONG` | 독립형 전사 미디어가 2시간을 초과함 |
| 400 | `INVALID_BRAND_VOCABULARY` | 요청별 용어집 항목이 제한을 위반함 |
| 400 | `TARGET_LANGUAGE_REQUIRED` | 번역된 전사 요청에서 언어가 누락됨 |
| 404 | `TRANSCRIPT_NOT_FOUND` | 요청한 원본 또는 번역된 전사가 없음 |
| 409 | `TRANSCRIPT_NOT_READY` | 요청한 전사가 여전히 처리 중임 |
| 502 | `TRANSCRIPTION_EMPTY` | 전사에 사용할 수 있는 음성이 포함되어 있지 않음 |
| 502 | `TRANSCRIPTION_FAILED` | 전사를 완료할 수 없음 |
| 400 | `INVALID_MULTIPART_REQUEST` | 멀티파트 업로드 요청 형식이 잘못되었거나 제한을 초과함 |

## 더빙 옵션 오류

| 상태 | 코드 | 의미 |
| - | - | - |
| 400 | `INVALID_SOURCE_SRT` | sourceSrt에 유효한 SRT 큐가 포함되어 있지 않음 |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt에는 명시적인 originalLanguage가 필요함 |
| 400 | `INVALID_TRANSLATED_SRT` | translatedSrt에 유효한 SRT 큐가 없습니다 |
| 400 | `TRANSLATED_SRT_CUE_COUNT_MISMATCH` | translatedSrt와 sourceSrt의 큐 수가 다릅니다 |
| 409 | `DUB_ONLY_REQUIRES_TRANSCRIPTION` | 더빙할 완료된 전사가 프로젝트에 없습니다 |
| 409 | `TRANSLATION_ALREADY_IN_PROGRESS` | 해당 언어의 더빙이 이미 진행 중입니다 |
| 400 | `VOICE_ID_REQUIRED` | 맞춤 음성 모드에는 음성 ID가 필요함 |
| 400 | `VOICE_ID_NOT_ALLOWED_WITH_CLONING` | voiceId가 음성 복제와 결합됨 |
| 400 | `VOICE_CLONING_SETTINGS_NOT_ALLOWED` | 복제 설정이 맞춤 음성 모드와 결합됨 |
| 400 | `CONFLICTING_LIPSYNC_OPTIONS` | 최신 및 레거시 립싱크 필드가 일치하지 않음 |
| 400 | `TRANSLATION_TIME_SKIP_REQUIRES_BACKGROUND` | 시간 건너뛰기에는 배경 오디오가 필요함 |
| 400 | `TRANSLATION_TIME_SKIP_CONFLICT` | 시간 건너뛰기가 원본 음성 유지와 충돌함 |
| 400 | `TRANSLATION_TIME_SKIP_OUT_OF_RANGE` | 시간 건너뛰기가 미디어 지속 시간을 초과함 |
| 400 | `INVALID_TRANSLATION_TIME_SKIPS` | 시간 건너뛰기가 전사 세그먼트와 겹침 |
| 400 | `SUBTITLES_NOT_AVAILABLE_FOR_AUDIO` | 자막 삽입에는 비디오 입력이 필요함 |
| 400 | `LIPSYNC_NOT_AVAILABLE_FOR_AUDIO` | 립싱크에는 비디오 입력이 필요함 |
| 400 | `TRANSLATION_TIME_SKIP_NOT_AVAILABLE_FOR_AUDIO` | 번역 시간 건너뛰기에는 비디오 입력이 필요함 |
| 403 | `CUSTOM_VOICE_ACCESS_DENIED` | 선택한 음성은 카탈로그 음성도 아니고 인증된 계정이 저장한 사용자 지정 음성도 아닙니다. |
| 403 | `LIPSYNC_MODE_ACCESS_DENIED` | 프리미엄 립싱크 모드는 해당 플랜에서 사용할 수 없음 |

## 비동기 SRT 정렬 오류

이 오류는 번역 또는 더빙 요청이 수락된 후에 발생합니다. 상태 엔드포인트는 HTTP 200과 `status: "failed"`를 반환하며, 해당 `error`와 `project.translation.failed` 웹훅에는 `code`와 `message`만 포함됩니다. 저장된 실패는 고정된 VoiceCheap 메시지를 사용하며 큐 번호나 세그먼트 인덱스는 포함하지 않습니다. `TRANSLATED_SRT_CUE_COUNT_MISMATCH` 같은 동기 요청 오류는 위 표에서 HTTP 400으로 유지됩니다.

| 결과 | Code | 의미 |
| - | - | - |
| `GET` 200 / webhook | `TRANSLATED_SRT_UNMATCHED_CUES` | 번역 큐가 어떤 전사 세그먼트와도 일치하지 않습니다(상태와 웹훅으로 보고) |
| `GET` 200 / webhook | `TRANSLATED_SRT_MISSING_SEGMENTS` | 전사 세그먼트에 번역 큐가 없습니다(상태와 웹훅으로 보고) |

## 인증 오류

> [accordion] MISSING\_API\_KEY
>
> **HTTP 상태:** 401
>
> `x-api-key` 헤더가 제공되지 않았습니다.
>
> **해결 방법:** `x-api-key` 헤더에 API 키를 포함하세요.
>
> ```json theme={null}
> {
>   "code": "MISSING_API_KEY",
>   "message": "API key is required. Please provide your API key in the x-api-key header."
> }
> ```

> [accordion] INVALID\_API\_KEY\_FORMAT
>
> **HTTP 상태:** 401
>
> API 키가 예상되는 `vc_` 접두사를 사용하지 않습니다.
>
> **해결 방법:** VoiceCheap 앱에서 전체 키를 복사했는지 확인하세요.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY_FORMAT",
>   "message": "Invalid API key format. API keys must start with \"vc_\"."
> }
> ```

> [accordion] INVALID\_API\_KEY
>
> **HTTP 상태:** 401
>
> 입력한 API 키가 유효하지 않습니다.
>
> **해결 방법:** API 키가 올바른지, 그리고 `x-api-key` 헤더에 포함되어 있는지 확인하세요.
>
> ```json theme={null}
> {
>   "code": "INVALID_API_KEY",
>   "message": "Invalid API key. Please check your API key and try again."
> }
> ```

> [accordion] SUBSCRIPTION\_REQUIRED
>
> **HTTP 상태:** 403
>
> API 및 MCP 액세스를 위해서는 Starter 플랜 이상이 필요합니다.
>
> **해결 방법:** [voicecheap.ai](https://voicecheap.ai/pricing)에서 Starter 플랜 이상으로 업그레이드하세요.
>
> ```json theme={null}
> {
>   "code": "SUBSCRIPTION_REQUIRED",
>   "message": "A Starter plan or higher is required to use the API and MCP. Please upgrade your account at voicecheap.ai/pricing."
> }
> ```

> [accordion] INSUFFICIENT\_CREDITS
>
> **HTTP 상태:** 403
>
> 귀하의 계정에 이 요청을 처리할 충분한 크레딧이 없습니다.
>
> **해결 방법:** 크레딧을 추가로 구매하거나 구독 플랜을 업그레이드하세요.
>
> ```json theme={null}
> {
>   "code": "INSUFFICIENT_CREDITS",
>   "message": "Insufficient credits to process this file. Please add more credits to your account."
> }
> ```

## 기타 인증 및 팀 오류

| HTTP | 코드 | 설명 |
| - | - | - |
| 401 | `USER_NOT_FOUND` | 이 키에 연결된 계정을 찾을 수 없습니다 |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | 키 소유자가 여러 팀에 속해 있습니다. 지원팀에 문의하세요 |
| 403 | `TEAM_OWNER_NOT_FOUND` | 연결된 팀 소유자 계정을 찾을 수 없습니다 |

## 파일 유효성 검사 오류

> [accordion] FILE\_REQUIRED
>
> **HTTP 상태:** 400
>
> 요청과 함께 업로드된 파일이 없습니다.
>
> **해결 방법:** 멀티파트 폼 데이터의 `file` 필드에 파일을 포함하세요.
>
> ```json theme={null}
> {
>   "code": "FILE_REQUIRED",
>   "message": "A video or audio file is required. Please upload a file with your request."
> }
> ```

> [accordion] INVALID\_FILE\_TYPE
>
> **HTTP 상태:** 400
>
> 업로드된 파일 형식은 지원되지 않습니다.
>
> **해결 방법:** 지원되는 형식(MP4, MOV, MKV, WebM, MPEG, MP3, WAV, M4A, FLAC, OGG, AAC) 중 하나로 파일을 업로드하세요.
>
> ```json theme={null}
> {
>   "code": "INVALID_FILE_TYPE",
>   "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
> }
> ```

> [accordion] FILE\_TOO\_LARGE
>
> **HTTP 상태:** 413
>
> 업로드된 파일이 인증된 구독 허용량을 초과했습니다: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB 또는 Enterprise 60 GB.
>
> **해결 방법:** 플랜 제한을 확인한 후 파일을 압축하거나 더 작은 세그먼트로 분할하거나 플랜을 업그레이드하세요.
>
> ```json theme={null}
> {
>   "code": "FILE_TOO_LARGE",
>   "message": "File size exceeds the 5GB limit for the beginner plan.",
>   "maximumFileSizeBytes": 5368709120
> }
> ```

> [accordion] DURATION\_DETECTION\_FAILED
>
> **HTTP 상태:** 400
>
> 업로드된 파일의 길이를 감지할 수 없습니다.
>
> **해결 방법:** 파일이 손상되지 않은 유효한 비디오 또는 오디오 파일인지 확인하세요.
>
> ```json theme={null}
> {
>   "code": "DURATION_DETECTION_FAILED",
>   "message": "Could not detect the duration of the uploaded file. Please ensure the file is a valid video or audio file."
> }
> ```

## 유효성 검사 오류

> [accordion] INVALID\_TARGET\_LANGUAGE
>
> **HTTP 상태:** 400
>
> 지정된 대상 언어는 지원되지 않습니다.
>
> **해결 방법:** [지원되는 언어](https://api-docs.voicecheap.ai/docs/ko/introduction.md#supported-languages) 중 하나를 사용하세요.
>
> ```json theme={null}
> {
>   "code": "VALIDATION_ERROR",
>   "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
> }
> ```

> [accordion] INVALID\_BOOLEAN\_VALUE
>
> **HTTP 상태:** 400
>
> 불리언 매개변수가 잘못된 값을 수신했습니다.
>
> **해결 방법:** `true` 또는 `false`을 사용하세요(form-data의 문자열로).
>
> ```json theme={null}
> {
>   "code": "INVALID_BOOLEAN_VALUE",
>   "message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
> }
> ```

> [accordion] INVALID\_JSON\_FORMAT
>
> **HTTP 상태:** 400
>
> JSON 매개변수를 구문 분석할 수 없습니다.
>
> **해결 방법:** JSON 문자열 형식이 올바른지 확인하세요.
>
> ```json theme={null}
> {
>   "code": "INVALID_JSON_FORMAT",
>   "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
> }
> ```

> [accordion] INVALID\_NUMBER\_VALUE
>
> **HTTP 상태:** 400
>
> 선택적 숫자 form-data 필드가 유효한 숫자가 아닙니다. 문서화된 범위 내의 숫자 값을 보내세요.

> [accordion] LIPSYNC\_VIDEO\_TOO\_LONG
>
> **HTTP 상태:** 400
>
> 지원되는 립싱크 지속 시간보다 긴 미디어에 대해 립싱크가 요청되었습니다.
>
> **해결 방법:** 이 요청에서 `lipsyncPro`을 생략하거나 립싱크 제한 내의 미디어 파일을 제출하세요.
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_VIDEO_TOO_LONG",
>   "message": "LipSync supports up to 180 minutes. Your video is 181 minutes long."
> }
> ```

## 리소스 오류

> [accordion] PROJECT\_NOT\_FOUND
>
> **HTTP 상태:** 404
>
> 지정된 프로젝트가 존재하지 않습니다.
>
> **해결 방법:** 프로젝트 ID가 올바른지 확인하세요.
>
> ```json theme={null}
> {
>   "code": "PROJECT_NOT_FOUND",
>   "message": "Project with ID 'abc123' not found."
> }
> ```

> [accordion] FORBIDDEN
>
> **HTTP 상태:** 403
>
> 이 리소스에 액세스할 권한이 없습니다.
>
> **해결 방법:** 이 프로젝트에 올바른 API 키를 사용하고 있는지 확인하세요.
>
> ```json theme={null}
> {
>   "code": "FORBIDDEN",
>   "message": "You do not have permission to access this project."
> }
> ```

## 권한 및 사용량 오류

| 상태 | 코드 | 조치 |
| - | - | - |
| 401 | `API_KEY_EXPIRED`, `INVALID_MCP_TOKEN` | 만료되지 않은 유효한 키를 사용하거나 어시스턴트를 다시 연결하세요. |
| 403 | `INSUFFICIENT_SCOPE` | 필수 권한을 부여하거나 다른 자격 증명을 선택하세요. |
| 403 | `SUBSCRIPTION_REQUIRED` | Starter 플랜 이상을 사용하세요. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 월간 초기화를 기다리거나 요금제를 변경하세요. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED`, `RATE_LIMIT_EXCEEDED` | 재시도 전에 대기하고 재시도 간격을 늘리세요. |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | 진행 중인 생성이 완료될 때까지 기다리세요. |
| 400 | `VALIDATION_ERROR` | 카탈로그의 입력 스키마에 따라 인수를 수정하세요. |
| 404 | `UNKNOWN_ACTION` | 검색 결과에 있는 지원되는 작업 이름을 사용하세요. |

계정의 공통 허용량은 [사용량 및 제한](https://api-docs.voicecheap.ai/docs/ko/api-reference/limits.md)을 확인하세요. 오류는 월간 호출 수를 소모하지 않습니다. `action_request_get`, `usage_get`, `projects_status`, `GET /v1/translate/{projectId}/status`는 월간 허용량에서 제외됩니다.

## 처리 오류

이러한 오류는 번역 상태를 확인할 때 `error` 필드에 반환될 수 있습니다:

> [accordion] TRANSCRIPTION\_FAILED
>
> 오디오를 전사할 수 없습니다.
>
> **가능한 원인:**
>
> * 오디오 품질이 너무 낮음
> * 오디오에서 음성이 감지되지 않음
> * 지원되지 않는 오디오 인코딩
>
> ```json theme={null}
> {
>   "code": "TRANSCRIPTION_FAILED",
>   "message": "The transcription could not be completed. Please try again."
> }
> ```

> [accordion] TRANSLATION\_FAILED
>
> 전사 내용을 번역할 수 없습니다.
>
> **가능한 원인:**
>
> * 지원되지 않는 언어 쌍
> * 콘텐츠를 처리할 수 없습니다
>
> ```json theme={null}
> {
>   "code": "TRANSLATION_FAILED",
>   "message": "The translation could not be completed. Please try again."
> }
> ```

> [accordion] LIPSYNC\_FAILED
>
> 립싱크 처리 실패.
>
> **가능한 원인:**
>
> * 립싱크 처리 중 일시적인 문제
> * 유효하지 않거나 지원되지 않는 미디어
> * 요청이 거부되거나 취소됨
>
> ```json theme={null}
> {
>   "code": "LIPSYNC_FAILED",
>   "message": "Lip sync could not be completed. Please try again."
> }
> ```

## 서버 오류

> [accordion] INTERNAL\_ERROR
>
> **HTTP 상태:** 500
>
> 서버에서 예기치 않은 오류가 발생했습니다.
>
> **해결 방법:** 요청을 다시 시도하십시오. 문제가 지속되면 지원팀에 문의하십시오.
>
> ```json theme={null}
> {
>   "code": "INTERNAL_ERROR",
>   "message": "An unexpected error occurred. Please try again later."
> }
> ```

## 오류 처리

```javascript JavaScript theme={null}
try {
  const response = await fetch('https://api.voicecheap.ai/v1/translate', {
    method: 'POST',
    headers: { 'x-api-key': apiKey },
    body: formData,
  });

if (!response.ok) {
const error = await response.json();

    switch (error.code) {
      case 'MISSING_API_KEY':
      case 'INVALID_API_KEY':
      case 'INVALID_API_KEY_FORMAT':
        // Check API key configuration
        break;
      case 'INSUFFICIENT_CREDITS':
        // Prompt user to add credits
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Implement backoff and retry
        break;
      case 'CONCURRENT_TRANSLATION_LIMIT_REACHED':
        // Wait for an in-progress translation to finish
        break;
      default:
        // Handle other errors
        console.error(`Error: ${error.message}`);
    }

}
} catch (err) {
// Handle network errors
console.error(err);
}

```

```python Python theme={null}
import requests
from requests.exceptions import RequestException

try:
    response = requests.post(
        'https://api.voicecheap.ai/v1/translate',
        headers={'x-api-key': api_key},
        files=files,
        data=data
    )

    if response.status_code != 200:
        error = response.json()

        if error['code'] in ['MISSING_API_KEY', 'INVALID_API_KEY', 'INVALID_API_KEY_FORMAT']:
            # Check API key configuration
            pass
        elif error['code'] == 'INSUFFICIENT_CREDITS':
            # Prompt user to add credits
            pass
        elif error['code'] == 'RATE_LIMIT_EXCEEDED':
            # Implement backoff and retry
            pass
        elif error['code'] == 'CONCURRENT_TRANSLATION_LIMIT_REACHED':
            # Wait for an in-progress translation to finish
            pass
        else:
            print(f"Error: {error['message']}")

except RequestException as e:
    # Handle network errors
    print(f"Network error: {e}")
```


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