最佳實踐

故障排除

常見問題、錯誤代碼及其快速解決方案。若此處未找到答案，請查閱常見問題或聯絡支援團隊。

常見錯誤代碼

代碼訊息原因解決方法
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 代碼，請在模型目錄中檢查模型名稱（區分大小寫）。並查看狀態頁面。

連線問題

「連線被拒絕」／「名稱解析失敗」

  • 確認 Base URL：https://api.tokspan.com/v1（請注意：是 https://，不是 http://）
  • 檢查您的防火牆／代理是否允許透過連接埠 443 的出口 HTTPS
  • DNS 測試：nslookup api.tokspan.com 應返回一個 IP 位址

「SSL 憑證錯誤」

  • 確保您系統的 CA 憑證是最新的
  • 檢查您的系統時鐘是否準確（SSL 憑證具有時效性）
  • 我們使用 Let's Encrypt 憑證——所有主流作業系統皆信任此憑證

「請求逾時」

  • 預設逾時時間因 SDK 而異。請明確設定：聊天最少 60 秒，長時間生成則為 120 秒
  • 使用串流（stream: true）——您無需等待完整回應即可接收 Token
  • 若特定模型持續發生逾時，上游供應商可能速度較慢——請嘗試更快或更輕量的模型

快速診斷檢查清單

提交支援工單前，請先執行以下檢查：

  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 並帶有內容，則您的金鑰和 Base URL 皆正確。
  2. 模型名稱是否正確？——檢查模型目錄。常見錯誤：使用「gpt4」而非「gpt-4o」。
  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+ 或 polyfill globalThis.fetch

仍然卡住？

聯絡支援時請附上以下資訊——這將大幅加快解決速度：

  • 您的帳戶電子郵件
  • 錯誤回應中的請求 ID（id 欄位）
  • 完整的錯誤回應主體與 HTTP 狀態碼
  • 您正在呼叫的模型以及可重現問題的最小程式碼片段
  • 您的 SDK 版本（pip show openai / npm list openai）

請寄送電子郵件至 support@tokspan.com——我們會在 24 小時內回覆。