エラー
リクエストが失敗すると、Shisa サービスは HTTP ステータスコードと、何が問題だったかを記述する JSON ボディで問題を通知します。本ガイドでは、目にすることになるステータスコード、詳細を伝える JSON の形、そしてエンドポイントごとのエラーテーブルの場所について説明します。
HTTP ステータスコード
まずレスポンスのステータスを確認してください — それが問題のカテゴリと解決方法を示します。
| Status | Meaning | How to resolve |
|---|---|---|
400 | 不正なリクエスト — 無効または不足しているパラメータ | リクエストボディと必須フィールドを確認してください。具体的なフィールドについてはエラーメッセージを参照してください。 |
401 | 認証に失敗 | API キーとサービスごとのヘッダー形式を確認してください。認証を参照してください。 |
429 | レート制限を超過 | ペースを落とし、バックオフを使ってリトライしてください。レート制限を参照してください。 |
500 | サーバーエラーまたはサービスが準備未完了 | 短い遅延の後にリトライしてください。続く場合は、プラットフォームからサポートにお問い合わせください。 |
JSON エラーの形
エラーボディは、サービス全体で 2 つの形があります。常に最初に HTTP ステータスを読み、その後に人間が読める error フィールドを得るためにボディを解析してください。
シンプルなエラー
一部のエンドポイントは、数値の code と error メッセージを持つコンパクトなボディを返します。たとえば、音声が添付されていない ASR リクエストの場合は次のようになります。
{
"code": 400,
"error": "No audio data provided"
}
認証エラー
認証の失敗（ASR と TTS で見られます）は、ミドルウェアと名前付きエラー型も識別する、より詳細なボディを返します。
{
"context": ["authMiddleware"],
"code": 104,
"name": "ErrAuthenticationFailed",
"error": "Authentication error: Invalid token"
}
Invalid token エラーは、ほぼ必ずそのサービスに対する Authorization ヘッダーが間違っていることを意味します — たとえば、ASR や翻訳で shsk: プレフィックスが欠けている場合などです。サービスごとのヘッダー規約を確認してください。
ボディを解析する前に、常に response.ok（またはステータスコード）を確認してください。429 や 500 には、成功パスが期待する JSON が含まれていない可能性があります。そのため、最初にステータスで分岐することで、2 つ目の紛らわしい解析エラーを避けられます。
実際に、解析する前にステータスを確認する例を示します。
const response = await fetch(url, options);
if (!response.ok) {
const detail = await response.json().catch(() => ({}));
throw new Error(`Shisa request failed (${response.status}): ${detail.error ?? 'unknown error'}`);
}
const data = await response.json();
response = requests.post(url, headers=headers, json=payload)
if not response.ok:
detail = response.json() if response.content else {}
raise RuntimeError(f"Shisa request failed ({response.status_code}): {detail.get('error', 'unknown error')}")
data = response.json()
サービスごとのエラー詳細
エラーフィールドと正確なメッセージはエンドポイントによって異なります。エンドポイント固有のエラーテーブルとリクエスト要件については、各サービスの API リファレンスを参照してください。
- ASR — エンドポイントリファレンス
- TTS — エンドポイントリファレンス
- Translation — エンドポイントリファレンス
- LLM — レスポンスは OpenAI 互換スキーマに従います。LLM セクションを参照してください。