> ## 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 | `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
不支持指定的语言。
**解决方案：** 使用 [supported languages](/docs/zh/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
可选的数字 form-data 字段不是有效的数字。请发送文档规定范围内的数值。
**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` | 每分钟 10 次请求 |
| `POST /v1/projects` | 每分钟 10 次请求 |
| `GET /v1/translate/{id}/status` | 每分钟 30 次请求 |
| `GET /v1/projects/{id}` | 每分钟 20 次请求 |
| `DELETE /v1/translate/{id}` | 每分钟 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}")
```