错误 | ElevenLabs Documentation

API 错误

ElevenLabs 使用标准 HTTP 状态码表示请求成功或失败。此外，所有 API 请求都会返回一个 JSON 对象，其中的 detail 属性包含错误信息。

通常，200 HTTP 状态码表示请求成功。4xx 代码表示请求存在问题，例如参数无效或缺少必填字段。500 HTTP 状态码表示 ElevenLabs 服务器出现问题，这种情况应较少发生。

错误属性

属性	说明
`type`	发生的错误类型。可能的值请参见下表。
`code`	错误代码。它比类型更具体，可用于确定错误原因。
`message`	错误消息，提供有关错误的更多详情。
`status`	错误状态。这是一个不再使用的旧字段，请改用 `code` 属性。
`request_id`	错误的请求 ID。这是请求的唯一标识符，可用于排查错误。
`param`	导致错误的参数。如果是验证错误，该字段会指明无效参数。

错误响应示例

以下是使用错误模型 ID 的 API 请求响应：

{
  "detail": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "The 'keyterms' parameter is only supported with the 'scribe_v2' model. You specified 'scribe_v1'.",
    "status": "invalid_parameters",
    "request_id": "3c807fc4c3a1705f9638ecc764a91c01",
    "param": "keyterms"
  }
}

通过这些错误属性可以看到，这是一个验证错误，代码为 invalid_parameters。消息提供了错误的更多详情，request_id 是可用于排查错误的请求唯一标识符。param 属性指明了导致错误的参数。

SDK 错误处理

ElevenLabs SDK 提供类型化错误类，可让你访问错误详情。

from elevenlabs import ElevenLabs
from elevenlabs.core import ApiError
elevenlabs = ElevenLabs()
try:
    audio = elevenlabs.text_to_speech.convert(
        voice_id="invalid-voice-id",
        model_id="eleven_v4",
        text="Hello, world!",
    )
except ApiError as e:
    print(f"Status code: {e.status_code}")
    # Access the error body
    if e.body and "detail" in e.body:
        detail = e.body["detail"]
        print(f"Error type: {detail.get('type')}")
        print(f"Error code: {detail.get('code')}")
        print(f"Message: {detail.get('message')}")
        print(f"Request ID: {detail.get('request_id')}")
        # Handle specific error types
        if detail.get("type") == "rate_limit_error":
            print("Rate limited - implement exponential backoff")
        elif detail.get("type") == "authentication_error":
            print("Check your API key")

速率限制和并发

如果收到 429 HTTP 状态码，说明你可能在短时间内发出了过多请求，超出了 API 端点的速率限制；或者超出了该 API 端点的并发限制。相应的错误 code 分别为 rate_limit_exceeded 或 concurrent_limit_exceeded。

遇到速率限制时，收到 429 错误后，应在代码中实施指数退避。这意味着在重试请求前增加延迟。

遇到并发限制时，应等待当前请求完成后再发起新请求。更多信息请参阅并发和优先级部分。

错误类型

错误会包含 type 属性，用于指明发生的错误类型。可能的值请参见下表。

类型	说明	HTTP 状态码
`validation_error`	请求包含无效参数值。	400
`invalid_request`	请求结构格式错误或缺少必填字段。	400
`authentication_error`	身份验证失败：API 密钥/令牌无效或缺失。	401
`payment_required`	用户积分不足或需要付款。	402
`authorization_error`	已验证身份的用户没有执行此操作所需的权限。	403
`not_found`	未找到请求的资源。	404
`conflict`	请求与资源的当前状态冲突。	409
`rate_limit_error`	请求过多，请稍后重试。	429
`internal_error`	发生意外服务器错误。	500
`service_unavailable`	服务暂时不可用，这种情况应较少发生。	503

错误代码

代码	类型	说明
`voice_not_found`	`not_found`	指定的音色 ID 不存在。请确认音色 ID 后重试。
`sample_not_found`	`not_found`	未找到指定的音色样本。
`voice_collection_not_found`	`not_found`	指定的音色集合不存在。
`user_not_found`	`not_found`	未找到指定用户。
`auth_account_not_found`	`not_found`	未找到身份验证账户。
`workspace_not_found`	`not_found`	指定的工作区不存在。
`project_not_found`	`not_found`	未找到指定项目。
`history_item_not_found`	`not_found`	指定的历史记录项不存在。
`collection_not_found`	`not_found`	未找到指定集合。
`document_not_found`	`not_found`	指定文档不存在。
`file_not_found`	`not_found`	未找到指定文件。
`conversation_not_found`	`not_found`	指定对话不存在。
`agent_not_found`	`not_found`	未找到指定智能体。
`dubbing_not_found`	`not_found`	指定的配音项目不存在。
`song_not_found`	`not_found`	未找到指定歌曲。
`read_not_found`	`not_found`	未找到指定的阅读内容。
`pronunciation_dictionary_not_found`	`not_found`	指定的发音词典不存在。
`knowledge_base_not_found`	`not_found`	未找到指定知识库。
`phone_number_not_found`	`not_found`	指定电话号码不存在。
`tool_not_found`	`not_found`	未找到指定工具。
`snapshot_not_found`	`not_found`	指定快照不存在。
`task_not_found`	`not_found`	未找到指定任务。
`model_not_found`	`not_found`	指定模型不存在。
`transcript_not_found`	`not_found`	未找到指定转录文本。
`keywords_list_not_found`	`not_found`	未找到指定关键词列表。
`category_not_found`	`not_found`	未找到指定类别。
`text_too_long`	`validation_error`	提供的文本超过允许的最大长度。
`text_too_short`	`validation_error`	提供的文本短于要求的最小长度。
`invalid_text`	`validation_error`	提供的文本包含无效字符或格式。
`empty_text`	`validation_error`	文本字段不能为空。
`invalid_parameters`	`validation_error`	一个或多个请求参数无效。请查看 `param` 属性以确认无效参数。
`missing_required_field`	`validation_error`	请求缺少必填字段。请查看 `param` 属性以确认缺失的字段。
`invalid_voice_settings`	`validation_error`	音色设置包含无效值。请查看 `param` 属性以确认无效的音色设置。
`invalid_voice_id`	`validation_error`	音色 ID 格式无效。
`unsupported_model`	`validation_error`	指定模型不支持此操作。
`invalid_audio`	`validation_error`	提供的音频无效或已损坏。
`invalid_audio_format`	`validation_error`	不支持指定的音频格式。
`invalid_output_format`	`validation_error`	不支持请求的输出格式。
`audio_too_long`	`validation_error`	音频超过允许的最长时长。
`audio_too_short`	`validation_error`	音频短于要求的最短时长。
`invalid_file_type`	`validation_error`	不支持该文件类型。
`invalid_page_size`	`validation_error`	页面大小参数超出允许范围。
`invalid_cursor`	`validation_error`	分页游标无效或已过期。
`bad_request`	`invalid_request`	服务器无法理解该请求。
`malformed_json`	`invalid_request`	请求正文包含无效 JSON。
`invalid_content_type`	`invalid_request`	Content-Type 标头缺失或无效。
`request_too_large`	`invalid_request`	请求正文超过允许的最大大小。
`invalid_api_key`	`authentication_error`	提供的 API 密钥无效。
`missing_api_key`	`authentication_error`	请求中未提供 API 密钥。
`invalid_authorization_header`	`authentication_error`	Authorization 标头格式无效。
`unauthorized`	`authentication_error`	访问此资源需要进行身份验证。
`sign_in_required`	`authentication_error`	必须登录才能执行此操作。
`forbidden`	`authorization_error`	禁止访问此资源。
`insufficient_permissions`	`authorization_error`	你没有执行此操作所需的权限。
`workspace_access_denied`	`authorization_error`	你无权访问此工作区。
`feature_not_available`	`authorization_error`	当前套餐不提供此功能。
`subscription_required`	`authorization_error`	访问此功能需要付费订阅。
`voice_access_denied`	`authorization_error`	你无权访问此音色。
`model_access_denied`	`authorization_error`	你无权访问此模型。
`conflict`	`conflict`	发生冲突。
`resource_already_exists`	`conflict`	具有相同标识符的资源已存在。
`voice_already_exists`	`conflict`	此名称的音色已存在。
`already_running`	`conflict`	操作已在运行。
`already_processing`	`conflict`	资源正在处理中。
`concurrent_modification`	`conflict`	资源已被其他请求修改。请使用最新版本重试。
`slug_already_exists`	`conflict`	使用此 slug 的资源已存在。
`rate_limit_exceeded`	`rate_limit_error`	请求过多。请等待后重试。
`concurrent_limit_exceeded`	`rate_limit_error`	超出最大并发请求数。更高订阅套餐具有更高的并发限制。
`system_busy`	`rate_limit_error`	系统当前繁忙。请稍后重试。
`insufficient_credits`	`payment_required`	账户没有足够积分执行此操作。
`internal_error`	`internal_error`	发生意外错误。如果问题持续存在，请联系支持团队。
`service_unavailable`	`service_unavailable`	服务暂时不可用。请稍后重试。
`maintenance`	`service_unavailable`	服务正在进行计划维护。