OneMux/文件中心/常見問題

常見問題

API 呼叫遇到錯誤？依狀態碼快速定位問題。本頁列出最常見的錯誤碼及解決方法，多數問題 1 分鐘內即可自行解決。

快速排查

程式碼發生錯誤時，先找到 HTTP 狀態碼（如 401、429），再對照處理：

狀態碼原因解決方法
401API Key 無效檢查金鑰格式（sk-xxx）和有效性
402餘額不足前往控制台儲值
404模型 ID 錯誤從模型頁面複製正確的 ID
429請求過於頻繁降低頻率，10 秒後重試
500上游服務故障稍後重試或切換模型

401 - API Key 無效

最常見原因：

  • 複製時多了空格
  • 格式不正確（不是 sk- 開頭）
  • 金鑰已刪除

快速解決：

# ✅ 正確格式
api_key = "sk-1234567890abcdef"

# ❌ 常見錯誤
api_key = " sk-1234567890abcdef "  # 前後有空格
api_key = "1234567890abcdef"       # 缺少 sk- 前綴

前往控制台重新複製或建立新金鑰。

402 - 餘額不足

帳戶餘額不足以支付此次請求。

前往費用中心儲值即可。

注意： 長上下文請求（如 Gemini 處理 100 萬 tokens）會預扣可能的最高費用，請確保餘額充足。

404 - 模型不存在

常見原因：

  • 模型 ID 拼寫錯誤
  • 使用了舊模型名稱（如 gpt-4o 已由 gpt-6.1-sol 取代）
  • Base URL 路徑錯誤

解決方法：

取得正確的模型 ID

  1. 1

    前往模型頁面

    開啟 https://onemux.net/models

  2. 2

    找到需要的模型

    搜尋或瀏覽以找到目標模型

  3. 3

    複製模型 ID

    點擊複製按鈕或手動複製完整 ID

確認 Base URL 為 https://api.onemux.net/v1（請注意結尾有 /v1）

429 - 請求過於頻繁

短時間內傳送過多請求，觸發頻率限制。

解決方法：

  • 降低請求頻率
  • 等待 10-30 秒後重試
  • 加入自動重試邏輯（請參閱錯誤處理文件）
  • 減少並行工作數量

500/502/503 - 服務故障

上游模型服務暫時無法使用。

解決方法：

  • 等待 10-30 秒後重試
  • 切換至其他模型
  • 檢查狀態頁面以瞭解服務狀態

不確定問題時的排查順序

逐步排查

  1. 1

    檢查餘額

    登入控制台確認餘額充足

  2. 2

    檢查 API Key

    重新複製完整金鑰，確保沒有空格

  3. 3

    檢查模型 ID

    從模型頁面重新複製

  4. 4

    檢查 Base URL

    確認為 https://api.onemux.net/v1

  5. 5

    重新啟動軟體

    儲存設定後重新啟動用戶端