> ## 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 | `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` | 프리미엄 립싱크 모드는 해당 플랜에서 사용할 수 없음 |
## 인증 오류
**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."
}
```
**HTTP 상태:** 401
API 키가 예상되는 `vc_` 접두사를 사용하지 않습니다.
**해결 방법:** VoiceCheap 앱에서 전체 키를 복사했는지 확인하세요.
```json theme={null}
{
"code": "INVALID_API_KEY_FORMAT",
"message": "Invalid API key format. API keys must start with \"vc_\"."
}
```
**HTTP 상태:** 401
제공된 API 키가 유효하지 않거나 만료되었습니다.
**해결 방법:** API 키가 올바른지, 그리고 `x-api-key` 헤더에 포함되어 있는지 확인하세요.
```json theme={null}
{
"code": "INVALID_API_KEY",
"message": "The provided API key is invalid. Please check your API key and try again."
}
```
**HTTP 상태:** 403
계정에 유효한 키가 있지만, 해당 계정에 API 액세스가 활성화되어 있지 않습니다.
**해결 방법:** API 액세스를 요청하거나 이미 API 액세스가 활성화된 계정을 사용하세요.
```json theme={null}
{
"code": "API_ACCESS_REQUIRED",
"message": "API access is required. Please request access to the API beta program."
}
```
**HTTP 상태:** 403
API 액세스를 위해서는 활성화된 유료 구독이 필요합니다.
**해결 방법:** [voicecheap.ai](https://voicecheap.ai/pricing)에서 유료 플랜으로 업그레이드하세요.
```json theme={null}
{
"code": "SUBSCRIPTION_REQUIRED",
"message": "API access requires an active paid subscription. Please upgrade your plan."
}
```
**HTTP 상태:** 403
귀하의 계정에 이 요청을 처리할 충분한 크레딧이 없습니다.
**해결 방법:** 크레딧을 추가로 구매하거나 구독 플랜을 업그레이드하세요.
```json theme={null}
{
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient credits to process this file. Please add more credits to your account."
}
```
## 파일 유효성 검사 오류
**HTTP 상태:** 400
요청과 함께 업로드된 파일이 없습니다.
**해결 방법:** 멀티파트 폼 데이터의 `file` 필드에 파일을 포함하세요.
```json theme={null}
{
"code": "FILE_REQUIRED",
"message": "A video or audio file is required. Please upload a file with your request."
}
```
**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, ..."
}
```
**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
}
```
**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."
}
```
## 유효성 검사 오류
**HTTP 상태:** 400
지정된 대상 언어는 지원되지 않습니다.
**해결 방법:** [지원되는 언어](/docs/ko/introduction#supported-languages) 중 하나를 사용하세요.
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}
```
**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\"."
}
```
**HTTP 상태:** 400
JSON 매개변수를 구문 분석할 수 없습니다.
**해결 방법:** JSON 문자열 형식이 올바른지 확인하세요.
```json theme={null}
{
"code": "INVALID_JSON_FORMAT",
"message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
}
```
**HTTP 상태:** 400
선택적 숫자 form-data 필드가 유효한 숫자가 아닙니다. 문서화된 범위 내의 숫자 값을 보내세요.
**HTTP 상태:** 400
지원되는 립싱크 지속 시간보다 긴 미디어에 대해 립싱크가 요청되었습니다.
**해결 방법:** 이 요청에서 `lipsyncPro`을 생략하거나 립싱크 제한 내의 미디어 파일을 제출하세요.
```json theme={null}
{
"code": "LIPSYNC_VIDEO_TOO_LONG",
"message": "LipSync supports up to 30 minutes. Your video is 45 minutes long."
}
```
## 리소스 오류
**HTTP 상태:** 404
지정된 프로젝트가 존재하지 않습니다.
**해결 방법:** 프로젝트 ID가 올바른지 확인하세요.
```json theme={null}
{
"code": "PROJECT_NOT_FOUND",
"message": "Project with ID 'abc123' not found."
}
```
**HTTP 상태:** 403
이 리소스에 액세스할 권한이 없습니다.
**해결 방법:** 이 프로젝트에 올바른 API 키를 사용하고 있는지 확인하세요.
```json theme={null}
{
"code": "FORBIDDEN",
"message": "You do not have permission to access this project."
}
```
## 속도 제한
**HTTP 상태:** 429
이 엔드포인트에 대한 속도 제한을 초과했습니다.
**해결 방법:** 추가 요청을 하기 전에 기다리세요. 지수 백오프(exponential backoff)를 사용하세요.
| 엔드포인트 | 속도 제한 |
| ------------------------------- | --------- |
| `POST /v1/translate` | 분당 10회 요청 |
| `POST /v1/projects` | 분당 10회 요청 |
| `GET /v1/translate/{id}/status` | 분당 30회 요청 |
| `GET /v1/projects/{id}` | 분당 20회 요청 |
| `DELETE /v1/translate/{id}` | 분당 10회 요청 |
```json theme={null}
{
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please wait before trying again."
}
```
**HTTP 상태:** 429
이미 병렬로 실행 중인 최대 번역 수에 도달했습니다.
**해결 방법:** 진행 중인 번역 중 하나가 완료될 때까지 기다린 후 요청을 다시 시도하세요.
```json theme={null}
{
"code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
"message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
}
```
## 처리 오류
이러한 오류는 번역 상태를 확인할 때 `error` 필드에 반환될 수 있습니다:
오디오를 전사할 수 없습니다.
**가능한 원인:**
* 오디오 품질이 너무 낮음
* 오디오에서 음성이 감지되지 않음
* 지원되지 않는 오디오 인코딩
```json theme={null}
{
"code": "TRANSCRIPTION_FAILED",
"message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}
```
전사 내용을 번역할 수 없습니다.
**가능한 원인:**
* 지원되지 않는 언어 쌍
* 콘텐츠를 처리할 수 없습니다
```json theme={null}
{
"code": "TRANSLATION_FAILED",
"message": "Failed to translate the content. Please try again."
}
```
더빙 중 음성 합성 실패.
**가능한 원인:**
* 음성 복제 실패
* 오디오 생성 오류
```json theme={null}
{
"code": "VOICE_SYNTHESIS_FAILED",
"message": "Failed to generate the dubbed audio. Please try again."
}
```
립싱크 처리 실패.
**가능한 원인:**
* 립싱크 공급자 오류
* 유효하지 않거나 지원되지 않는 미디어
* 요청이 거부되거나 취소됨
```json theme={null}
{
"code": "LIPSYNC_FAILED",
"message": "Lip sync failed."
}
```
## 서버 오류
**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}")
```