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

某些错误可能包含附加字段。请求负载验证失败时，每个无效字段返回一个条目
在 `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 | **Internal Server Error** - 我们端出现错误 |
| 502 | **Bad Gateway** - 转录未能完成 |

## 转录和转录导出错误

| 状态 | 代码 | 含义 |
| - | - | - |
| 400 | `INVALID_MEDIA_STREAM` | 上传的媒体不包含音频流 |
| 400 | `DURATION_TOO_LONG` | 独立转录媒体时长超过两小时 |
| 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
>
> 不支持指定的语言。
>
> **解决方案：** 使用 [supported languages](https://api-docs.voicecheap.ai/docs/zh/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
>
> 可选的数字 form-data 字段不是有效的数字。请发送文档规定范围内的数值。

> [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] FORBIDDEN
>
> **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/zh/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] TRANSLATION\_FAILED
>
> 无法翻译转录内容。
>
> **可能的原因：**
>
> * 不支持的语言对
> * 无法处理内容
>
> ```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.