> ## 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 | `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/ja/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
オプションの数値フォームデータフィールドが有効な数値ではありません。ドキュメントに記載された範囲内の数値を送信してください。
**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
このエンドポイントのレート制限を超えました。
**解決策:** 追加のリクエストを行う前に待機してください。指数バックオフを使用してください。
| エンドポイント | レート制限 |
| ------------------------------- | ------------ |
| `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リクエスト |
```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}")
```