最佳實踐

故障排除

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

常見錯誤代碼

代碼訊息原因解決方法
401無效的 API 金鑰金鑰遺失、格式錯誤或已被撤銷檢查 Authorization: Bearer sk-... 標頭。在儀表板 → API 金鑰中確認金鑰為啟用狀態。金鑰以 sk- 開頭。
402餘額不足帳戶餘額為零或負值在儀表板 → 計費中新增點數。為生產金鑰啟用自動充值。
404找不到模型模型 ID 不存在或拼寫錯誤對照可用模型檢查模型名稱。模型名稱區分大小寫。
429超出速率限制當前時間窗口內請求或 Token 過多檢查 x-ratelimit-remaining-* 標頭。實作指數退避機制。請參閱速率限制。
500內部伺服器錯誤TokSpan 端問題使用退避機制重試。若持續超過 5 分鐘，請查看狀態頁面。
502閘道錯誤上游供應商故障或逾時重試——自動容錯移轉應將請求路由至您的備用模型。若持續發生，請設定容錯移轉鏈。
503服務無法使用暫時性過載等待並在 Retry-After 標頭指定的時間後重試。查看狀態頁面。

連線問題

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

  • 確認 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
  • 若特定模型持續發生逾時，上游供應商可能速度較慢——請嘗試其他模型或加上 -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 並帶有內容，則您的金鑰和 Base URL 皆正確。
  2. 模型名稱是否正確？——檢查模型目錄。常見錯誤：使用「gpt4」而非「gpt-4o」。
  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+ 或 polyfill globalThis.fetch

仍然卡住？

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

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

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