​
レスポンスステータスコード

Supertone APIは、標準のHTTPステータスコードを使用してAPIリクエストの成功または失敗を示します。

ステータスコード説明
200 - OKリクエストが正常に処理されました。
400 - Bad Requestリクエストを処理できません。必須パラメータが送信されていないか、パラメータのフォーマットが間違っている場合に返されるレスポンスです。エラーコードを参照してリクエストパラメータをご確認ください。
401 - UnauthorizedリクエストされたAPI keyが有効ではありません。
403 - ForbiddenAPI Keyにそのリクエストを行う権限がありません。
404 - Not Foundリクエストされたリソースが存在しません。リクエストしたAPIアドレスをもう一度ご確認ください。
500 - Internal Server ErrorSupertoneサーバーでエラーが発生しました。

​
エラーレスポンスの形式

リクエストが正常に処理されない場合、HTTPステータスコードとともに以下のようなエラーオブジェクトが返されます。

{
    "status": "error",
    "message": {
        "statusCode": 400,
        "message": [
            "The text must be less than 200 characters",
            "language must be one of the following values: en, ko, ja"
        ],
        "error": "Bad Request"
    }
}

{
  "status": "error",
  "message": {
    "statusCode": 500,
    "message": "Failed to convert text to speech",
    "error": "Internal Server Error"
  }
}

​
トラブルシューティングガイド

​
1. API キー関連の問題 (401, 403)

症状

  • 401 Unauthorized エラー
  • 403 Forbidden エラー
  • “Invalid API key” メッセージ
{
    "status": "error",
    "message": {
        "statusCode": 401,
        "message": "Invalid API key",
        "error": "Unauthorized"
    }
}

確認事項

  1. API キーの含有確認
    • すべてのリクエストのヘッダーにAPI キーが含まれているか確認
    • ヘッダー名が正確にx-sup-api-keyであるか確認
  2. API キーの形式
    • API キーに余分な空白が含まれていないか確認
    • API キーが完全にコピーされているか確認
  3. API キーの有効性
    • コンソールでAPI キーの状態を確認
    • API キーが期限切れになっていないか確認
    • API キーが破棄されていないか確認

解決方法

  • コンソールで新しいAPI キーを発行
  • 環境変数や設定ファイルのAPI キー値を更新
  • API キーに関する権限を再確認

​
2. 不正なリクエストの問題 (400)

症状

  • 400 Bad Request エラー
  • パラメータ関連のエラーメッセージ
  • リクエスト形式のエラーメッセージ
{
    "status": "error",
    "message": {
        "statusCode": 400,
        "message": [
            "language must be one of the following values: en, ko, ja"
        ],
        "error": "Bad Request"
    }
}

{
    "status": "error",
    "message": {
        "statusCode": 400,
        "message": [
            "The text must be less than 200 characters"
        ],
        "error": "Bad Request"
    }
}

確認事項

  1. 必須パラメータ
    • すべての必須パラメータが含まれているか確認
    • パラメータ名が正確であるか確認
  2. パラメータ形式
    • テキストの長さが200文字を超えていないか確認
    • JSON形式が正しいか確認
    • パラメータ値のデータタイプが正しいか確認
  3. エンコーディング
    • テキストエンコーディングがUTF-8であるか確認
    • 特殊文字が正しくエンコードされているか確認

解決方法

  • APIドキュメントのパラメータ仕様を再確認
  • リクエストボディのJSON形式を検証
  • テキストの長さとエンコーディングを調整

​
3. リソースアクセスの問題 (404, 500)

症状

  • 404 Not Found エラー
  • 500 Internal Server Error エラー
  • “Resource not found” メッセージ

確認事項

  1. APIエンドポイント
    • URLが正確であるか確認 (https://supertoneapi.com/v1/...)
    • APIバージョンが正しいか確認
  2. ボイスID
    • Get Voices APIを通じて利用可能なボイス一覧を確認
    • ボイスIDの大文字小文字が正確であるか確認
  3. アクセス権限
    • 該当ボイスへのアクセス権限があるか確認
    • サブスクリプション状態の確認
{
    "status": "error",
    "message": {
        "statusCode": 500,
        "message": "An error occurred while fetching the voice",
        "error": "Internal Server Error"
    }
}

解決方法

  1. Get Voices APIを通じて最新のボイス一覧を照会
  2. APIエンドポイントアドレスを再確認
  3. ボイスアクセス権限を確認

​
4. サーバーエラー (500)

症状

  • 500 Internal Server Error
  • サーバーレスポンスのタイムアウト
  • 予期しないエラーメッセージ

確認事項

  1. サーバーの状態
    • サービスステータスページを確認
    • 一時的なサーバーの問題であるか確認
  2. リクエスト頻度
    • リクエスト制限超過の有無を確認
    • 同時リクエスト数を確認
  3. ネットワークの状態
    • ネットワーク接続状態を確認
    • ファイアウォール設定を確認

解決方法

  • しばらく待って再試行
  • リクエスト間隔を調整
  • 継続的な問題が発生する場合は技術サポートチームに問い合わせ

​
エラー技術サポートへのお問い合わせ

問題の解決が困難な場合や問題が継続する場合は、以下の情報とともに技術サポートチームまでお問い合わせください。

  • メール: techsupport@supertone.ai
  • 必須情報:
    • API キーの末尾4桁（コンソールページで確認可能）
    • エラー発生時刻
    • リクエストしたAPIエンドポイント
    • エラーメッセージ全文
    • 再現手順
    • リクエスト/レスポンス例（機密情報を除く）