ベストプラクティス

トラブルシューティング

一般的な問題、エラーコード、およびそれらの迅速な解決方法について説明します。ここで回答が見つからない場合は、FAQを確認するかサポートにお問い合わせください。

一般的なエラーコード

コードメッセージ原因対処法
401無効なAPIキーキーが欠落、不正な形式、または失効しているAuthorization: Bearer sk-... ヘッダーを確認してください。ダッシュボード → APIキー でキーが有効であることを確認してください。キーは sk- で始まります。
404エンドポイントが見つかりませんリクエストURLがいずれのAPIエンドポイントにも一致しないAPI リファレンスと照合してリクエストパスを確認してください。注意：モデルが見つからないエラーは 503 とコード model_not_found で返されます — エラーコード をご覧ください。
429レート制限超過 / クォータ不足現在のウィンドウでリクエストが多すぎるか、アカウント/APIキーの残高が不足しているレート制限に対しては指数バックオフとジッターを実装してください。エラーメッセージがクォータや残高に言及している場合（例: insufficient_user_quota）、リトライせず ダッシュボード → 課金 でチャージしてください。レート制限 を参照してください。
500内部サーバーエラーTokSpan側の問題バックオフ付きでリトライしてください。5分以上継続する場合は ステータスページ を確認してください。
502不正なゲートウェイ上流プロバイダーがダウンまたはタイムアウトしているリトライしてください — 自動フェイルオーバーが同じモデルを提供するバックアッププロバイダーにルーティングするはずです。継続する場合は サポートにお問い合わせ ください。
503サービス利用不可 / モデルが見つかりません一時的な過負荷、またはモデルがこのキーで利用できないバックオフ付きで再試行してください — Retry-After ヘッダーには依存しないでください。エラーにコード model_not_found が含まれる場合、モデルカタログでモデル名を確認してください（大文字と小文字を区別）。ステータスページも確認してください。

接続の問題

「接続が拒否されました」／「名前解決に失敗しました」

  • ベースURLを確認してください: https://api.tokspan.com/v1（注意: https:// であり http:// ではありません）
  • ファイアウォール/プロキシがポート443での送信HTTPSを許可しているか確認してください
  • DNSテスト: nslookup api.tokspan.com がIPを返すことを確認してください

「SSL証明書エラー」

  • システムのCA証明書が最新であることを確認してください
  • システムクロックが正確であることを確認してください（SSL証明書は時刻に依存します）
  • 弊社はLet's Encrypt証明書を使用しています — すべての主要OSで信頼されています

「リクエストタイムアウト」

  • デフォルトのタイムアウトはSDKによって異なります。明示的に設定してください：チャットは最低60秒、長時間の生成は120秒
  • ストリーミング（stream: true）を使用してください — 完全なレスポンスを待たずにトークンを受信できます
  • 特定のモデルで一貫してタイムアウトが発生する場合、上流プロバイダーが遅い可能性があります — より高速または軽量なモデルを試してください

クイック診断チェックリスト

サポートチケットを発行する前に以下を確認してください：

  1. APIキーは有効ですか？ — 最小限のcurlでテストしてください：
    curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","messages":[{"role":"user","content":"Hi"}]}'
    401が返ってきた場合、キーに問題があります。200とコンテンツが返ってきた場合、キーとベースURLは正しいです。
  2. モデル名は正しいですか？ — モデルカタログ を確認してください。よくある間違い: "gpt-4o" の代わりに "gpt4" を使用すること。
  3. クレジットはありますか？ — ダッシュボード → 課金 を確認してください。残高が $0 より大きい必要があります。
  4. レート制限またはクォータ不足ではありませんか？ — 429 応答の場合は、並行処理を減らし、指数バックオフで再試行してください（Retry-After ヘッダーがあればそれに従います）。エラーがクォータ/残高に言及している場合は、ダッシュボード → 課金 で残高を確認してください。
  5. サービスは稼働していますか？ — APIステータスページ で進行中のインシデントを確認してください。

SDK固有の問題

Python（openai SDK）

  • ModuleNotFoundError: openai → pip install openai
  • openai.APIError / APIConnectionError → ネットワーク接続を確認してください。curl を直接試してSDKとネットワークの問題を切り分けてください。
  • プロキシ: 企業プロキシの背後にいる場合は http_client=httpx.Client(proxy="http://proxy:8080") を設定してください

Node.js（openai SDK）

  • Cannot find module 'openai' → npm install openai
  • ERR_MODULE_NOT_FOUND → ESMでは import を、CJSでは require('openai') を使用してください
  • fetch is not defined（Node 18未満）→ Node 18以上にアップグレードするか、globalThis.fetch をポリフィルしてください

まだ解決しませんか？

サポートに問い合わせる際は以下を含めてください — 解決が大幅に早まります：

  • アカウントのメールアドレス
  • エラーレスポンスの リクエストID（id フィールド）
  • 完全なエラーレスポンスボディとHTTPステータスコード
  • 呼び出しているモデルと問題を再現する最小限のコードスニペット
  • SDKのバージョン（pip show openai / npm list openai）

support@tokspan.com までメールでお問い合わせください — 24時間以内に返信いたします。