文件快速開始站內基礎教學
常見錯誤碼
遇到狀態碼時，先判斷問題類型，再依優先順序排查
很多人一看到錯誤就開始懷疑平台有問題，但實際上，MoleAPI 接入中的大多數錯誤都可以透過狀態碼 + 設定項快速定位。
最推薦的排查思路
不要一開始就全盤推翻設定。建議先按照這個順序判斷：
- 先看狀態碼是多少
- 再判斷是身分問題、權限問題、位址問題，還是請求內容問題
- 最後回到控制台檢查對應設定
錯誤碼速查
| 狀態碼 | 常見含義 | 你應該優先檢查什麼 |
|---|---|---|
| 400 | 請求參數錯誤 | JSON 結構、欄位類型、模型是否支援該參數 |
| 401 | 驗證失敗 | API Key 是否正確、是否多了空格、是否已失效 |
| 403 | 權限不足 | 模型權限、分組、IP 白名單、Key 限額 |
| 404 | 位址或路由錯誤 | Base URL 是否正確、是否漏了 /v1、路徑是否拼錯 |
| 429 | 限流或額度問題 | 請求頻率、並發、餘額、配額或限額是否觸發 |
| 500 | 伺服器端異常 | 先重試並保留請求資訊，持續出現再聯絡支援 |
依狀態碼理解
400：請求本身有問題
這種錯誤通常表示：
- 你的請求結構不對
- 某個欄位類型不對
- 你傳給模型了它不支援的參數
如果你最近剛換了模型、換了 SDK，或是複製了別人的範例程式碼，優先先看這裡。
401：API Key 有問題
優先檢查：
- 你填的是不是 MoleAPI 控制台建立的
sk-... - 前後有沒有空格
- 有沒有複製不完整
- 是否誤把其他平台的 Key 填進來了
403：能存取介面，但沒有權限這麼做
這種錯誤最常見於：
- 目前 Key 沒有該模型權限
- 目前分組不支援這個模型
- 設定了 IP 白名單，但來源 IP 不匹配
- Key 本身額度或限制被觸發
404：位址錯了
這是新手最常見的問題之一。
優先檢查：
- Base URL 是否填寫成
https://api.moleapi.com/v1 - 是否仍在請求
api.openai.com - 是否把完整介面路徑錯誤地填成 Base URL
429：被限制了，或者額度不夠了
看到 429 時，不要只想到「請求太快了」，還要同時檢查：
- 餘額是否不足
- Key 是否有限額
- 是否並發過高
- 是否在短時間內請求太密集
500：伺服器端異常
如果是偶發的，可以先重試；如果是穩定重現的，建議保留：
- 請求時間
- 模型名
- 請求參數
- Request ID（如果用戶端有）
這樣後續排查會快很多。
一個非常實用的排查順序
當你不知道從哪開始時，按照這個順序最省時間：
- 看狀態碼
- 看 Base URL
- 看 API Key
- 看模型名
- 看分組 / 權限 / 限額
- 看餘額和日誌
經驗法則
404 多半先看位址；401 多半先看 Key；403 多半先看權限；429 不只看頻率，也要看餘額與限額。
下一步建議看什麼
這篇文件對您有幫助嗎？
最後更新於