오류 코드

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

오류 응답 형식

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

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}

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

{
  "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`	프리미엄 립싱크 모드는 해당 플랜에서 사용할 수 없음

인증 오류

MISSING_API_KEY

HTTP 상태: 401x-api-key 헤더가 제공되지 않았습니다.해결 방법: x-api-key 헤더에 API 키를 포함하세요.

{
  "code": "MISSING_API_KEY",
  "message": "API key is required. Please provide your API key in the x-api-key header."
}

INVALID_API_KEY_FORMAT

HTTP 상태: 401API 키가 예상되는 vc_ 접두사를 사용하지 않습니다.해결 방법: VoiceCheap 앱에서 전체 키를 복사했는지 확인하세요.

{
  "code": "INVALID_API_KEY_FORMAT",
  "message": "Invalid API key format. API keys must start with \"vc_\"."
}

INVALID_API_KEY

HTTP 상태: 401제공된 API 키가 유효하지 않거나 만료되었습니다.해결 방법: API 키가 올바른지, 그리고 x-api-key 헤더에 포함되어 있는지 확인하세요.

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid. Please check your API key and try again."
}

API_ACCESS_REQUIRED

HTTP 상태: 403계정에 유효한 키가 있지만, 해당 계정에 API 액세스가 활성화되어 있지 않습니다.해결 방법: API 액세스를 요청하거나 이미 API 액세스가 활성화된 계정을 사용하세요.

{
  "code": "API_ACCESS_REQUIRED",
  "message": "API access is required. Please request access to the API beta program."
}

SUBSCRIPTION_REQUIRED

HTTP 상태: 403API 액세스를 위해서는 활성화된 유료 구독이 필요합니다.해결 방법: voicecheap.ai에서 유료 플랜으로 업그레이드하세요.

{
  "code": "SUBSCRIPTION_REQUIRED",
  "message": "API access requires an active paid subscription. Please upgrade your plan."
}

INSUFFICIENT_CREDITS

HTTP 상태: 403귀하의 계정에 이 요청을 처리할 충분한 크레딧이 없습니다.해결 방법: 크레딧을 추가로 구매하거나 구독 플랜을 업그레이드하세요.

{
  "code": "INSUFFICIENT_CREDITS",
  "message": "Insufficient credits to process this file. Please add more credits to your account."
}

파일 유효성 검사 오류

FILE_REQUIRED

HTTP 상태: 400요청과 함께 업로드된 파일이 없습니다.해결 방법: 멀티파트 폼 데이터의 file 필드에 파일을 포함하세요.

{
  "code": "FILE_REQUIRED",
  "message": "A video or audio file is required. Please upload a file with your request."
}

INVALID_FILE_TYPE

HTTP 상태: 400업로드된 파일 형식은 지원되지 않습니다.해결 방법: 지원되는 형식(MP4, MOV, MKV, WebM, MPEG, MP3, WAV, M4A, FLAC, OGG, AAC) 중 하나로 파일을 업로드하세요.

{
  "code": "INVALID_FILE_TYPE",
  "message": "Invalid file type \"application/pdf\". Supported formats: video/mp4, video/quicktime, ..."
}

FILE_TOO_LARGE

HTTP 상태: 413업로드된 파일이 인증된 구독 허용량을 초과했습니다: Beginner 5 GB, Starter 10 GB, Creator 20 GB, Pro 30 GB, Scale 40 GB 또는 Enterprise 60 GB.해결 방법: 플랜 제한을 확인한 후 파일을 압축하거나 더 작은 세그먼트로 분할하거나 플랜을 업그레이드하세요.

{
  "code": "FILE_TOO_LARGE",
  "message": "File size exceeds the 5GB limit for the beginner plan.",
  "maximumFileSizeBytes": 5368709120
}

DURATION_DETECTION_FAILED

HTTP 상태: 400업로드된 파일의 길이를 감지할 수 없습니다.해결 방법: 파일이 손상되지 않은 유효한 비디오 또는 오디오 파일인지 확인하세요.

{
  "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."
}

유효성 검사 오류

INVALID_TARGET_LANGUAGE

HTTP 상태: 400지정된 대상 언어는 지원되지 않습니다.해결 방법: 지원되는 언어 중 하나를 사용하세요.

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid target language. Allowed languages: arabic, brazilian portuguese, british english, ..."
}

INVALID_BOOLEAN_VALUE

HTTP 상태: 400불리언 매개변수가 잘못된 값을 수신했습니다.해결 방법: true 또는 false을 사용하세요(form-data의 문자열로).

{
  "code": "INVALID_BOOLEAN_VALUE",
  "message": "Invalid boolean value for \"keepBackgroundMusic\". Expected \"true\" or \"false\", got \"yes\"."
}

INVALID_JSON_FORMAT

HTTP 상태: 400JSON 매개변수를 구문 분석할 수 없습니다.해결 방법: JSON 문자열 형식이 올바른지 확인하세요.

{
  "code": "INVALID_JSON_FORMAT",
  "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
}

INVALID_NUMBER_VALUE

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

LIPSYNC_VIDEO_TOO_LONG

HTTP 상태: 400지원되는 립싱크 지속 시간보다 긴 미디어에 대해 립싱크가 요청되었습니다.해결 방법: 이 요청에서 lipsyncPro을 생략하거나 립싱크 제한 내의 미디어 파일을 제출하세요.

{
  "code": "LIPSYNC_VIDEO_TOO_LONG",
  "message": "LipSync supports up to 30 minutes. Your video is 45 minutes long."
}

리소스 오류

PROJECT_NOT_FOUND

HTTP 상태: 404지정된 프로젝트가 존재하지 않습니다.해결 방법: 프로젝트 ID가 올바른지 확인하세요.

{
  "code": "PROJECT_NOT_FOUND",
  "message": "Project with ID 'abc123' not found."
}

FORBIDDEN

HTTP 상태: 403이 리소스에 액세스할 권한이 없습니다.해결 방법: 이 프로젝트에 올바른 API 키를 사용하고 있는지 확인하세요.

{
  "code": "FORBIDDEN",
  "message": "You do not have permission to access this project."
}

속도 제한

RATE_LIMIT_EXCEEDED

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회 요청

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait before trying again."
}

CONCURRENT_TRANSLATION_LIMIT_REACHED

HTTP 상태: 429이미 병렬로 실행 중인 최대 번역 수에 도달했습니다.해결 방법: 진행 중인 번역 중 하나가 완료될 때까지 기다린 후 요청을 다시 시도하세요.

{
  "code": "CONCURRENT_TRANSLATION_LIMIT_REACHED",
  "message": "Concurrent translation limit reached. You can run up to 10 translations at the same time."
}

처리 오류

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

TRANSCRIPTION_FAILED

오디오를 전사할 수 없습니다.가능한 원인:

오디오 품질이 너무 낮음
오디오에서 음성이 감지되지 않음
지원되지 않는 오디오 인코딩

{
  "code": "TRANSCRIPTION_FAILED",
  "message": "Could not transcribe the audio. Please ensure the audio quality is sufficient."
}

TRANSLATION_FAILED

전사 내용을 번역할 수 없습니다.가능한 원인:

지원되지 않는 언어 쌍
콘텐츠를 처리할 수 없습니다

{
  "code": "TRANSLATION_FAILED",
  "message": "Failed to translate the content. Please try again."
}

VOICE_SYNTHESIS_FAILED

더빙 중 음성 합성 실패.가능한 원인:

음성 복제 실패
오디오 생성 오류

{
  "code": "VOICE_SYNTHESIS_FAILED",
  "message": "Failed to generate the dubbed audio. Please try again."
}

LIPSYNC_FAILED

립싱크 처리 실패.가능한 원인:

립싱크 공급자 오류
유효하지 않거나 지원되지 않는 미디어
요청이 거부되거나 취소됨

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync failed."
}

서버 오류

INTERNAL_ERROR

HTTP 상태: 500서버에서 예기치 않은 오류가 발생했습니다.해결 방법: 요청을 다시 시도하십시오. 문제가 지속되면 지원팀에 문의하십시오.

{
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred. Please try again later."
}

오류 처리

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);
}

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}")

개요

전사

번역

레퍼런스

오류 코드

오류 코드

오류 응답 형식

HTTP 상태 코드

전사 및 전사 내보내기 오류

더빙 옵션 오류

인증 오류

파일 유효성 검사 오류

유효성 검사 오류

리소스 오류

속도 제한

처리 오류

서버 오류

오류 처리

​오류 코드

​오류 응답 형식

​HTTP 상태 코드

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

​더빙 옵션 오류

​인증 오류

​파일 유효성 검사 오류

​유효성 검사 오류

​리소스 오류

​속도 제한

​처리 오류

​서버 오류

​오류 처리

오류 코드

오류 응답 형식

HTTP 상태 코드

전사 및 전사 내보내기 오류

더빙 옵션 오류

인증 오류

파일 유효성 검사 오류

유효성 검사 오류

리소스 오류

속도 제한

처리 오류

서버 오류

오류 처리