ベストプラクティス

トラブルシューティング

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

一般的なエラーコード

コードメッセージ原因対処法
401無効なAPIキーキーが欠落、不正な形式、または失効しているAuthorization: Bearer sk-... ヘッダーを確認してください。ダッシュボード → APIキー でキーが有効であることを確認してください。キーは sk- で始まります。
402残高不足アカウント残高がゼロまたはマイナスダッシュボード → 課金 でクレジットを追加してください。本番キーでは 自動トップアップ を有効にしてください。
404モデルが見つかりませんモデルIDが存在しないか、スペルミスがある利用可能なモデル でモデル名を確認してください。モデル名は大文字と小文字が区別されます。
429レート制限を超過しました現在のウィンドウでリクエストまたはトークンが多すぎるx-ratelimit-remaining-* ヘッダーを確認してください。指数バックオフを実装してください。レート制限 を参照してください。
500内部サーバーエラーTokSpan側の問題バックオフ付きでリトライしてください。5分以上継続する場合は ステータスページ を確認してください。
502不正なゲートウェイ上流プロバイダーがダウンまたはタイムアウトしているリトライしてください — 自動フェイルオーバーがバックアップモデルにルーティングするはずです。継続する場合は フェイルオーバーチェーン を設定してください。
503サービス利用不可一時的な過負荷Retry-After ヘッダーの値の後に待機してリトライしてください。ステータスページ を確認してください。

接続の問題

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

  • ベース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）を使用してください — 完全なレスポンスを待たずにトークンを受信できます
  • 特定のモデルで一貫してタイムアウトが発生する場合、上流プロバイダーが遅い可能性があります — 別のモデルを試すか -fast サフィックスを追加してください

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

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

  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":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'
    401が返ってきた場合、キーに問題があります。200とコンテンツが返ってきた場合、キーとベースURLは正しいです。
  2. モデル名は正しいですか？ — モデルカタログ を確認してください。よくある間違い: "gpt-4o" の代わりに "gpt4" を使用すること。
  3. クレジットはありますか？ — ダッシュボード → 課金 を確認してください。残高が $0 より大きい必要があります。
  4. レート制限されていませんか？ — レスポンスヘッダーの x-ratelimit-remaining-requests を確認してください。0の場合はウィンドウがリセットされるのを待ってください。
  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時間以内に返信いたします。