API呼び出し中に発生する可能性のある主要なエラータイプとその解決方法をご案内します。Supertone APIではHTTPステータスコードを通じて問題の原因をご案内しており、この文書を通じてどのような状況でどのようなエラーが発生する可能性があるかを事前に確認できます。

​
1. エラーコード一覧

​
400 Bad Request

リクエスト形式自体に問題がある場合です。最も一般的な原因は以下の通りです：

  • text、languageなどの必須フィールドが欠落している場合
  • styleまたはmodelの値に存在しない値を入力した場合
  • voice_settingsのパラメータ値が許可範囲を超えている場合（例：pitch_shift: 20）
  • JSONが無効、または完全に間違った形式で送信した場合
  • テキスト長が300文字を超えた場合

リクエストボディをもう一度確認してください。 エディターやLinterを使用してJSON構造を検証することもお勧めします。

​
401 Unauthorized

API Keyが欠落しているか、正しくない場合です。

  • x-sup-api-keyヘッダーがない場合
  • 正しくないキーを使用している場合（他のアカウントキー、期限切れキーなど）

コンソールで発行されたAPI Keyを正確に入力したか確認してください。 文字列コピー時に前後のスペースが含まれないよう注意が必要です。

​
402 Not Enough Credits

API呼び出しを処理できるほどのクレジットが残っていない場合です。

  • クレジットが0、または呼び出し予想コストより不足している場合
  • Play/コンソールでプランを決済していない場合

Play購読ページでプランを決済するか、クレジットをチャージした後に再試行してください。
クローンボイスを呼び出す際も同様にクレジットが差し引かれます。

​
403 Forbidden

使用権限のないリソースにアクセスしようとした時に発生します。

  • そのvoice_idが自分のアカウント所有でない場合（例：他のユーザーのクローンボイス）
  • 企業アカウントのサブユーザーが呼び出し権限のないリソースを使用しようとする場合
  • コンソールで発行されていないAPI Keyを使用する場合

GET /v1/voicesを呼び出して、そのボイスの利用権限の有無を再確認してみてください。
クローンボイスは作成したアカウントでのみ呼び出しできます。
アカウントが異なる場合は403が発生します。

​
404 Not Found

指定したリソースが見つからない時に発生します。

  • 存在しないvoice_idを使用した場合
  • GET /voices/searchで狭すぎる条件でフィルタリングして結果が0件の時
  • エンドポイントパスのタイプミス

リクエストパスとパラメータ値が正確か再確認してください。
voice_idはコンソールまたはGET /voicesで確認可能です。

​
408 Request Timeout

サーバーが一定時間内にリクエストを処理できなかった時に発生します。

  • ネットワークが不安定、またはリクエストボディが大きすぎて複雑な時
  • サーバー内部的に処理遅延が発生した場合

同じリクエストが繰り返しタイムアウトする場合は、カスタマーサポートを通じてお問い合わせください。
リクエストを単純化するか、入力値を減らして再試行できます。

​
429 Too Many Requests

一定時間内にリクエストが過度に送信された場合です。

  • 基本呼び出し制限はアカウント当たり20回/分です
  • この基準を超えると一時的にレスポンスが遅延またはブロックされる可能性があります

しばらく待ってから再度リクエストを送信してください。
エンタープライズユーザーの場合、呼び出し制限の上向き調整が可能です。（エンタープライズお問い合わせ）

​
500 Internal Server Error

予期しないサーバー内部エラーです。

  • 一時的なサーバー問題の可能性が高いです
  • リクエスト自体に問題がなくても間欠的に発生する可能性があります

同じリクエストが繰り返し失敗する場合は、リクエストボディを含めてカスタマーサポートを通じてお問い合わせください。
発生時点をログとして残しておくことが問題解決に役立ちます。

​
2. よく発生するケースの要約

  • リクエストボディを送信せずに呼び出して400が発生
  • API KeyをPostman環境変数として間違って設定して401が発生
  • クローンボイスを他のアカウントから呼び出そうとして403が発生
  • クレジットを使い切って再度呼び出したら402が発生
  • 入力テキストが310文字で400が発生（300文字制限超過）

​
3. エラー対応のコツ

  • ほとんどのエラーはHTTPステータスコードと共に即座に把握可能です
  • エラーメッセージには詳細な説明が含まれていないため、リクエスト内容を丁寧に検討してみてください
  • 繰り返し発生するエラーは、リクエストボディとヘッダー内容を含めてカスタマーサポートを通じてお問い合わせください。