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.