エラーコード

VoiceCheap APIは標準的なHTTPステータスコードを使用し、エラーを適切に処理できるように構造化されたエラーレスポンスを返します。

エラーレスポンス形式

すべてのエラーレスポンスは、以下の構造に従います：

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

一部のエラーには追加フィールドが含まれる場合があります。リクエストペイロードの検証に失敗した場合、各項目につき1つのエントリが返されます。 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	内部サーバーエラー - サーバー側で問題が発生しました
502	不正なゲートウェイ - 処理エンジンが失敗しました

文字起こしおよび文字起こしのエクスポートエラー

ステータス	コード	意味
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オプションの数値フォームデータフィールドが有効な数値ではありません。ドキュメントに記載された範囲内の数値を送信してください。

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

禁止されています

HTTPステータス: 403このリソースにアクセスする権限がありません。解決策: このプロジェクトに対して正しいAPIキーを使用していることを確認してください。

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

レート制限

RATE_LIMIT_EXCEEDED

HTTPステータス: 429このエンドポイントのレート制限を超えました。解決策: 追加のリクエストを行う前に待機してください。指数バックオフを使用してください。

エンドポイント	レート制限
`POST /v1/translate`	1分あたり10リクエスト
`POST /v1/projects`	1分あたり10リクエスト
`GET /v1/translate/{id}/status`	1分間に30リクエスト
`GET /v1/projects/{id}`	1分間に20リクエスト
`DELETE /v1/translate/{id}`	1分間に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."
}

翻訳に失敗しました

文字起こしを翻訳できませんでした。考えられる原因:

サポートされていない言語ペア
コンテンツを処理できませんでした

{
  "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ステータスコード

文字起こしおよび文字起こしのエクスポートエラー

吹き替えオプションのエラー

認証エラー

ファイル検証エラー

検証エラー

リソースエラー

レート制限

処理エラー

サーバーエラー

エラーの処理