错误代码

VoiceCheap API 使用标准的 HTTP 状态代码，并返回结构化的错误响应，以帮助您妥善处理错误。

错误响应格式

所有错误响应均遵循此结构：

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error"
}

某些错误可能包含附加字段。请求负载验证失败时，每个无效字段返回一个条目在 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	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 报告）

身份验证错误

MISSING_API_KEY

HTTP 状态： 401未提供 x-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不支持指定的语言。解决方案： 使用 supported languages 之一。

{
  "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 状态： 400无法解析 JSON 参数。解决方案： 确保 JSON 字符串格式正确。

{
  "code": "INVALID_JSON_FORMAT",
  "message": "Invalid JSON format for \"voiceCloningSettings\". Please provide valid JSON."
}

INVALID_NUMBER_VALUE

HTTP 状态： 400可选的数字 form-data 字段不是有效的数字。请发送文档规定范围内的数值。

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

FORBIDDEN

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

TRANSLATION_FAILED

无法翻译转录内容。可能的原因：

不支持的语言对
无法处理内容

{
  "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 对齐错误

身份验证错误

其他身份验证和团队错误

文件验证错误

验证错误

资源错误

权限和使用量错误

处理错误

服务器错误

处理错误