> ## 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"
}
```

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

## 認証エラー

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

> [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] 禁止されています
>
> **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/ja/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] 翻訳に失敗しました
>
> 文字起こしを翻訳できませんでした。
>
> **考えられる原因:**
>
> * サポートされていない言語ペア
> * コンテンツを処理できませんでした
>
> ```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.