エラー | ElevenLabs Documentation

APIエラー

ElevenLabsは、リクエストの成功または失敗を示すために標準のHTTPステータスコードを使用します。さらに、すべてのAPIリクエストは、エラーに関する情報を含むdetailプロパティを持つJSONオブジェクトを返します。

一般に、HTTPステータスコード200はリクエストが成功したことを示します。4xxコードは、無効なパラメーターや必須フィールドの不足など、リクエストに問題があることを示します。HTTPステータスコード500はElevenLabsのサーバーに問題があることを示しますが、これはまれです。

エラープロパティ

プロパティ	説明
`type`	発生したエラーの種類です。可能な値については、以下の表を参照してください。
`code`	エラーコードです。typeよりも具体的で、エラーの原因を特定するために使用できます。
`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_v3",
        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")

レート制限と同時実行数

HTTPステータスコード429を受け取った場合、短時間にリクエストを多く送信して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`	1つ以上のリクエストパラメーターが無効です。無効なパラメーターは`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`	このスラッグを持つリソースがすでに存在します。
`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`	サービスは定期メンテナンス中です。