エラー | 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_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`	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`	サービスは定期メンテナンス中です。