エラー

リクエストが​失敗すると、​Shisa サービスは​ HTTP ステータスコードと、​何が​問題だったかを​記述する​ JSON ボディで​問題を​通知します。​本ガイドでは、​目に​する​ことに​なる​ステータスコード、​詳細を​伝える​ JSON の​形、​そして​エンドポイントごとの​エラーテーブルの​場所に​ついて​説明します。

HTTP ステータスコード

まずレスポンスの​ステータスを​確認してください​ — それが​問題の​カテゴリと​解決方​法を​示します。

Status	Meaning	How to resolve
400	不正な​リクエスト — 無効または​不足している​パラメータ	リクエストボディと​必須フィールドを​確認してください。​具体的な​フィールドに​ついては​エラーメッセージを​参照してください。
401	認証に​失敗	APIキー全体と​ベアラーヘッダーを​確認してください。認証を​参照してください。
403	アクセスを​拒否	キーは​有効ですが、​要求した​サービス、​プロバイダー、​または​モデルを​利用できません。
404	サービス/プロバイダーが​見つからない、​または​非公開モデルが​隠されている	ルート/モデルと​キーの​アクセス権を​確認してください。
429	レート制限を​超過	ペースを​落とし、​バック​オフを​使ってリトライしてください。レート制限を​参照してください。
500	ルーターまたは​バックエンドの​内部​障害	短い​遅延の​後に​リトライしてください。​続く​場合は、プラットフォームから​サポートに​お問い​合わせください。
502	選択された​バックエンドに​接続できない	バック​オフして​再試行してください。​ルーターと​バックエンド間で​障害が​発生しています。
503	サービス、​依存先、​または​WebSocket受け入れ処理が​一時的に​利用不可	エンドポイント固有の​エラーが​設定や​権限の​変更を​求めていない​限り、​バック​オフして​再試行してください。

JSON エラーの​形

エラーボディは、​ルーター生成レスポンスと​バックエンドから​転送された​レスポンスで​異なります。​まずHTTPステータスを​確認してください。​本文が​JSONの​場合、errorは​文字列の​場合も、codeやmessageを​含むオブジェクトの​場合も​あります。

ルーターエラー

ルーターが​生成する​HTTPエラーの​多くには、​数値コード、​エラー名、​コンテキスト、​文字列メッセージが​含まれます。

{
  "context": ["authMiddleware"],
  "code": 104,
  "name": "ErrAuthenticationFailed",
  "error": "Authentication error: Invalid token"
}

構造化エラーと​バックエンドエラー

一部の​検証エラーや​WebSocket受け入れエラーでは、errorが​オブジェクトに​なります。

{
  "error": {
    "code": "tts_text_too_long",
    "message": "TTS text exceeds maximum length",
    "max_chars": 5000,
    "actual_chars": 5001
  }
}

バックエンドは​別の​JSON形式や​JSON以外の​本文を​返すことが​あり、​ルーターが​そのステータスと​本文を​そのまま​転送する​場合が​あります。​正確な​メッセージ文字列に​依存して​分岐しないでください。

ヒント

ボディを​解析する前に、​常に​ response.ok（または​ステータスコード）を​確認してください。429 や​ 500 には、​成功パスが​期待する​ JSON が​含まれていない​可能性が​あります。​その​ため、​最初に​ステータスで​分岐する​ことで、​2 つ目の​紛らわしい​解析エラーを​避けられます。

実際に、​解析する​前に​ステータスを​確認する​例を​示します。

const response = await fetch(url, options);
if (!response.ok) {
  const detail = await response.json().catch(() => null);
  const error = detail?.error;
  const message =
    typeof error === 'string'
      ? error
      : error?.message ?? detail?.message ?? response.statusText;
  throw new Error(`Shisa request failed (${response.status}): ${message}`);
}
const data = await response.json();

response = requests.post(url, headers=headers, json=payload)
if not response.ok:
    try:
        detail = response.json()
    except ValueError:
        detail = {}
    error = detail.get("error")
    message = error if isinstance(error, str) else (
        error.get("message") if isinstance(error, dict) else None
    )
    raise RuntimeError(
        f"Shisa request failed ({response.status_code}): "
        f"{message or detail.get('message') or response.reason}"
    )
data = response.json()

サービスごとの​エラー詳細

エラーフィールドと​正確な​メッセージは​エンドポイントに​よって​異なります。​エンドポイント固有の​エラーテーブルと​リクエスト要件に​ついては、​各サービスの​ API リファレンスを​参照してください。

• ASR — エンドポイントリファレンス
• TTS — エンドポイントリファレンス
• Translation — エンドポイントリファレンス
• LLM — レスポンスは​ OpenAI 互換スキーマに​従います。LLM セクションを​参照してください。

次の​ステップ

• レート制限 — リトライと​バック​オフで​ 429 を​処理する。
• 認証 — 401 エラーを​修正する。