トラブルシューティング

エラーの形は呼び出したプロトコルに一致します。 /v1/chat/completions および /v1/responses は OpenAI スタイルのエラーを返します。 /v1/messages は Anthropic スタイルのエラーを返します。HTTP ステータスコードは 3 つのプロトコルすべてで同一です。

エラーレスポンス形式

OpenAI 形式 (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Anthropic 形式 (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · 認証に失敗しました authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

原因

• Authorization: Bearer ヘッダー(または X-API-Key)がありません — メッセージ:missing API key in Authorization header or X-API-Key。
• キーが有効なキーのいずれにも一致しません — メッセージ:invalid API key。
• キーの有効期限が切れています — メッセージ:API key expired。

対処

1. Authorization: Bearer sk-syn-…(または X-API-Key: sk-syn-…)を送信します。
2. キーがコンソールで有効になっており、完全にコピーされていることを確認します。

400 · 無効なリクエスト invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

原因

• model フィールドが欠落しているか、JSON ボディが空または不正な形式です。

対処

1. model と正しい形式の JSON ボディを含めてください。Chat Completions リファレンスを参照してください。

403 · クォータ枯渇 quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

原因

• キーまたはワークスペースのプリペイド残高を使い切りました。

対処

1. ワークスペースの残高をチャージします。注意:残高を使い切ると Synthorai は 403 quota_exhausted を返し、429 ではありません — そのため指数バックオフは効果がなく、チャージのみで解除されます。

403 · コンプライアンス — データ共有なし compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

原因

• ワークスペースで no_provider_data_share が有効になっており、要求されたモデルはデータの保持/共有を必要とするプロバイダーからのみ提供されています(例:データ共有のみの Bedrock または Vertex モデル)。

対処

1. リクエストをゼロ保持モデルにルーティングするか、そのワークロードでデータ共有が許容される場合はワークスペースのコンプライアンススイッチをオフにします。保持クラスはモデルごとのルーティング入力です — 30 日間のデータ保持の詳細を参照してください。

429 · レート制限 rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

原因

• 1 分あたりのリクエスト上限(RPM)を超えました。メッセージに正確な上限が示されます。

対処

1. 指数バックオフ + ジッターでバックオフしてリトライします(下記スニペット)。継続的なスループットが必要な場合は上限の引き上げを申請してください。

502 · モデルに利用可能なチャネルがありません upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

原因

• モデル id がワークスペースのルーティング可能なチャネルに一致しません — タイプミス、提供終了したモデル、またはプランでは到達できないモデルです。

対処

1. 正確な id を最新のモデル一覧と照合してください。モデルが最近提供終了になった場合は、現行のモデルを選んでください。

BYOK:上流プロバイダーのエラー

bring-your-own-key では、リクエストはあなたのプロバイダーアカウント(AWS Bedrock、Google Vertex AI、または Anthropic API)で実行されるため、Synthorai はプロバイダーの元のエラーをそのまま透過します — レスポンスには usage.is_byok: true が含まれます。修正はゲートウェイではなく、そのプロバイダーのコンソールまたは設定にあります。最も一般的なのはアカウント単位のモデルアクセスとデータ共有の設定です:

上流プロバイダーのエラー

これらはモデルプロバイダーから、プロバイダー自身の HTTP ステータスと type を伴って透過されます。プロバイダー側を示すのは 500 と 529 のみで、これら(および 429)は一時的なものとして扱いリトライし、4xx はリクエスト側を反映します。完全なリファレンス:Anthropic のエラードキュメント。

レート制限

レート制限は API key ごとに適用され、すべてのユーザー間で公平な利用を保証します。

デフォルトの制限

実際のトークン単価に対してトークンスループットを見積もりますか?LLM API コスト計算ツールでワークロードを試算してください。

429 エラーの処理

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

特定のモデルで 502 や過負荷が発生していますか?モデル価格比較からフォールバックを選んでください — すべてのルーティング可能なモデルとトークン単価が 1 つの表にまとまっています。