Moknah ドキュメント
無料で始める
APIリファレンス

エラー

APIのエラーレスポンス、WebSocketのクローズコード、およびそれらの処理方法の理解

REST API エラー形式 (HTTP)

標準のHTTPエンドポイントでエラーが発生した場合、APIは以下の構造を持つJSONレスポンスを返します。

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "人間が理解できるエラーの説明",
        "details": {
          // 追加のコンテキスト(エラーの種類によって異なります)
        }
    }
}

WebSocket エラー形式 (WSS)

WebSocketにおけるエラーの扱いは異なります。エラーは、初期接続のハンドシェイク中、あるいは音声生成中のストリームの途中で発生する可能性があります。

  • 致命的なエラー: 特定のClose Code(例:4290)で接続が切断されます。
  • 処理途中のエラー: サーバーは接続を閉じる前に、フラットなJSONエラーフレームを送信します。 {"error": "配信中のクレジット不足"}

ステータスコードとクローズコード

HTTPステータスコード (REST)

ステータス 意味 説明
200 了解しました。 リクエストが成功しました
400 不正なリクエスト 無効なリクエストパラメータ、または不正な形式のリクエスト
401 未承認 APIキーが指定されていないか、無効です。
402 支払いが必要です リクエストを完了するためのクレジットが不足しています。
403 禁止 APIキーにはこの操作を行う権限がありません。
404 見つかりません 要求されたリソースは存在しません
409 対立 リクエストが現在の状態と競合しています(例:同時HTTPリクエスト)
429 リクエストが多すぎます レート制限を超過しました
500 内部サーバーエラー 当方で何らかの問題が発生しました。

WebSocket 終了コード (WSS)

コード タイプ 説明
1000 正常終了 ストリームが正常に完了しました。
3011 生成エラー アップストリームAPIでの音声生成に失敗しました。リクエストを再試行してください。
4001 認証情報がありません ハンドシェイク中、AuthorizationヘッダーにAPIキーが指定されていませんでした。
4002 認証失敗 無効なキー、無効なアカウント、初期クレジットの不足、またはIP制限。
4290 同時実行数制限 すでに有効なTTS WebSocket接続が存在します。ユーザーあたりの接続数は1つに制限されています。

一般的なエラーのシナリオ

1. 権限なし / 認証失敗

HTTP: 401 WSS: 4001 / 4002

APIキーの欠落・無効、またはIPホワイトリストの制限により、認証に失敗しました。

一般的な原因:

  • Authorization: Bearer ヘッダーがありません
  • APIキーの形式が無効であるか、キーが取り消されています。
  • キーのホワイトリストに含まれていないIPアドレスからの接続

2. クレジット不足

HTTP: 402 WSS: ストリーム途中のJSON

このリクエストを完了するために必要なクレジットが、お客様のアカウントには不足しています。

  • HTTP: 音声の生成直前に失敗します。
  • WebSocket: ストリームの途中でクレジットが尽きると、サーバーは~を送信します。 {"error": "配信中のクレジット不足"} そして、接続を適切に終了します。クレジットを使い切る前に生成された音声は、引き続き配信されます。

3. 同時実行数とレート制限

HTTP: 409 / 429 WSS: 4290

Moknah は、公平な利用を確保するため、ユーザー1人につき一度に1つのリクエストを処理します。

  • HTTP 409: お客様のアカウントからの別のリクエストが既に処理中です。完了するまでお待ちください。
  • HTTP 429: 1分間あたり60リクエスト(RPM)の制限を超えました。
  • WSS 4290: 最初のWebSocket接続がまだアクティブな状態で、2つ目の接続を開こうとしました。

4. 無効なリクエスト / 不正なデータ

HTTP: 400 WSS: ストリーム途中のJSON

リクエストパラメータが無効であるか、テキストチャンクの制限を超えています。

  • HTTP: 必須フィールド(text、voice_id)が不足しています。
  • WebSocket: 2,000文字を超えるテキストの塊を送信すると、 {"error": "チャンクが大きすぎます。1チャンクあたりの上限は2000文字です。"}.

コード内のエラー処理

import requests
import time

def generate_speech(text, voice_id, api_key):
    url = "https://moknah.io/api/v1/tts/generate"
    headers = {"Authorization": f"Bearer {api_key}"}

    response = requests.post(url, json={"text": text, "voice_id": voice_id}, headers=headers)

    if response.status_code == 200:
        return response.content  # 音声クリップ
    elif response.status_code == 402:
        raise Exception("クレジット不足")
    elif response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return generate_speech(text, voice_id, api_key)  # 再試行
    elif response.status_code == 409:
        time.sleep(5)
        return generate_speech(text, voice_id, api_key)  # 再試行
    else:
        raise Exception(f"API error: {response.status_code}")
async function generateSpeech(text, voiceId, apiKey) {
  const response = await fetch("https://moknah.io/api/v1/tts/generate", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ text: text, voice_id: voiceId })
  });

  if (response.ok) return await response.blob();

  if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After") || 5;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return generateSpeech(text, voiceId, apiKey);
  }

  if (response.status === 409) {
    await new Promise(r => setTimeout(r, 5000));
    return generateSpeech(text, voiceId, apiKey);
  }

  const error = await response.json();
  throw new Error(error.error?.message || "API Error");
}
const ws = new WebSocket('wss://moknah.io/api/v1/api/v1/tts/ws/', {
    headers: { "Authorization": `Bearer ${apiKey}` }
});

// Handle Mid-Stream JSON Errors
ws.on('message', (data, isBinary) => {
    if (!isBinary) {
        const msg = JSON.parse(data.toString());
        if (msg.error) {
            console.error("Stream Error:", msg.error);
            // e.g., "Insufficient credits during stream"
        }
    }
});

// Handle Fatal Close Codes
ws.on('close', (code, reason) => {
    switch(code) {
        case 1000:
            console.log("Stream finished successfully.");
            break;
        case 4001:
        case 4002:
            console.error("Authentication failed. Check your API key.");
            break;
        case 4290:
            console.error("Concurrency limit reached. Close other active streams.");
            // Wait a few seconds before attempting to reconnect
            setTimeout(reconnect, 5000);
            break;
        case 3011:
            console.error("Upstream generation failed. Please try again.");
            break;
        default:
            console.error(`Disconnected with code ${code}`);
    }
});
ベストプラクティス:指数バックオフ

429 (HTTP)、409 (HTTP)、および 4290 (WSS) エラーに対しては、指数バックオフ(1秒、2秒、4秒…と待機時間を延ばす手法)を実装してください。これにより、API への過度な負荷を防ぎ、ロックが解除された時点でリクエストが確実に成功するようになります。

APIサポート

APIに関するご質問や問題については、こちらまでお問い合わせください。 api@moknah.io.