エラーコード

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	`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 Webhook に含まれるのは code と message だけです。保存された失敗には VoiceCheap の固定メッセージを使用し、キュー番号やセグメントのインデックスは含まれません。TRANSLATED_SRT_CUE_COUNT_MISMATCH などの同期リクエストエラーは、上の表の HTTP 400 のままです。

結果	Code	意味
`GET` 200 / webhook	`TRANSLATED_SRT_UNMATCHED_CUES`	翻訳キューがどの文字起こしセグメントにも一致しません（ステータスと Webhook で報告）
`GET` 200 / webhook	`TRANSLATED_SRT_MISSING_SEGMENTS`	文字起こしセグメントに対応する翻訳キューがありません（ステータスと Webhook で報告）

認証エラー

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": "Invalid API key. Please check your API key and try again."
}

SUBSCRIPTION_REQUIRED

HTTPステータス: 403APIとMCPへのアクセスには、Starterプラン以上が必要です。解決策: voicecheap.aiでStarterプラン以上にアップグレードしてください。

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

INSUFFICIENT_CREDITS

HTTPステータス: 403このリクエストを処理するためのクレジットが不足しています。解決策: クレジットを追加購入するか、サブスクリプションプランをアップグレードしてください。

{
  "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`	紐づくチーム所有者のアカウントが見つかりません

ファイル検証エラー

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 180 minutes. Your video is 181 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."
}

権限と使用量のエラー

ステータス	コード	対処
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`	検出結果にある、対応するアクション名を使用してください。

アカウント共通の呼び出し枠については、使用状況と制限を参照してください。エラーは月間呼び出し数を消費しません。action_request_get、usage_get、projects_status、GET /v1/translate/{projectId}/status は月間呼び出し枠の対象外です。

処理エラー

翻訳ステータスを確認する際、errorフィールドに以下のエラーが返されることがあります：

TRANSCRIPTION_FAILED

音声を文字起こしできませんでした。考えられる原因：

音声品質が低すぎます
音声内に発話が検出されませんでした
サポートされていない音声エンコーディングです

{
  "code": "TRANSCRIPTION_FAILED",
  "message": "The transcription could not be completed. Please try again."
}

翻訳に失敗しました

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

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

{
  "code": "TRANSLATION_FAILED",
  "message": "The translation could not be completed. Please try again."
}

LIPSYNC_FAILED

リップシンク処理に失敗しました。考えられる原因:

リップシンク処理中の一時的な問題
無効またはサポートされていないメディア
リクエストが拒否またはキャンセルされました

{
  "code": "LIPSYNC_FAILED",
  "message": "Lip sync could not be completed. Please try again."
}

サーバーエラー

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

概要

ディスカバリー

アカウント

使用量とアクティビティ

設定と通知

チーム

プロジェクト

翻訳と吹き替え

文字起こしと編集

テキスト読み上げ

読み上げ音声

吹き替え音声

文字起こし

字幕とキャプション

画像

サムネイル

フォルダー

用語集

Webhook

公開

リクエストの状態

OAuth と MCP プロトコル

エラーコード

エラーコード

エラーレスポンス形式

HTTPステータスコード

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

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

非同期の SRT 対応付けエラー

認証エラー

その他の認証とチームのエラー

ファイル検証エラー

検証エラー

リソースエラー

権限と使用量のエラー

処理エラー

サーバーエラー

エラーの処理

​エラーコード

​エラーレスポンス形式

​HTTPステータスコード

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

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

​非同期の SRT 対応付けエラー

​認証エラー

​その他の認証とチームのエラー

​ファイル検証エラー

​検証エラー

​リソースエラー

​権限と使用量のエラー

​処理エラー

​サーバーエラー

​エラーの処理

エラーコード

エラーレスポンス形式

HTTPステータスコード

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

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

非同期の SRT 対応付けエラー

認証エラー

その他の認証とチームのエラー

ファイル検証エラー

検証エラー

リソースエラー

権限と使用量のエラー

処理エラー

サーバーエラー

エラーの処理