> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # 错误 ## API 错误 ElevenLabs 使用标准 HTTP 状态码表示请求成功或失败。此外，所有 API 请求都会返回一个 JSON 对象，其中的 `detail` 属性包含错误信息。 通常，`200` HTTP 状态码表示请求成功。`4xx` 代码表示请求存在问题，例如参数无效或缺少必填字段。`500` HTTP 状态码表示 ElevenLabs 服务器出现问题，这种情况应较少发生。 ### 错误属性 | 属性 | 说明 | | ------------ | -------------------------------- | | `type` | 发生的错误类型。可能的值请参见下表。 | | `code` | 错误代码。它比类型更具体，可用于确定错误原因。 | | `message` | 错误消息，提供有关错误的更多详情。 | | `status` | 错误状态。这是一个不再使用的旧字段，请改用 `code` 属性。 | | `request_id` | 错误的请求 ID。这是请求的唯一标识符，可用于排查错误。 | | `param` | 导致错误的参数。如果是验证错误，该字段会指明无效参数。 | ### 错误响应示例 以下是使用错误模型 ID 的 API 请求响应： ```json { "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 提供类型化错误类，可让你访问错误详情。 ```python 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") ``` ```typescript import { ElevenLabsClient, ElevenLabsError } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); try { const audio = await elevenlabs.textToSpeech.convert("invalid-voice-id", { text: "Hello, world!", modelId: "eleven_v4", }); } catch (error) { if (error instanceof ElevenLabsError) { console.log(`Status code: ${error.statusCode}`); // Access the error body const detail = (error.body as any)?.detail; if (detail) { console.log(`Error type: ${detail.type}`); console.log(`Error code: ${detail.code}`); console.log(`Message: ${detail.message}`); console.log(`Request ID: ${detail.request_id}`); // Handle specific error types if (detail.type === "rate_limit_error") { console.log("Rate limited - implement exponential backoff"); } else if (detail.type === "authentication_error") { console.log("Check your API key"); } } } } ``` 如果无法解决错误，请将错误响应中的 `request_id`、完整错误消息以及复现问题的步骤发送至 [support@elevenlabs.io](mailto:support@elevenlabs.io) 联系支持团队。 #### 速率限制和并发 如果收到 429 HTTP 状态码，说明你可能在短时间内发出了过多请求，超出了 API 端点的速率限制；或者超出了该 API 端点的并发限制。相应的错误 `code` 分别为 `rate_limit_exceeded` 或 `concurrent_limit_exceeded`。 遇到速率限制时，收到 429 错误后，应在代码中实施指数退避。这意味着在重试请求前增加延迟。 遇到并发限制时，应等待当前请求完成后再发起新请求。更多信息请参阅[并发和优先级](/docs/zh/overview/models#concurrency-and-priority)部分。 ### 错误类型 错误会包含 `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` 服务正在进行计划维护。