錯誤碼說明
401 / 403 / 404 / 429 / 5xx 的含義、五步排查法與減少報錯的做法。
呼叫失敗時，先看 HTTP 狀態碼與回應內容中的錯誤訊息，再對照下表。多數問題在前三項就能解決。
狀態碼
| 狀態 | 含義 | 常見原因與處理 |
|---|---|---|
| 400 Bad Request | 請求無效 | JSON 格式錯誤或缺少必填欄位（model、messages）；對照 API 文件檢查請求內容 |
| 401 Unauthorized | 鑑權失敗 | 金鑰錯誤 / 已刪除 / 已過期；請見鑑權方式的檢查清單 |
| 403 Forbidden | 無存取權 | 該金鑰或帳戶可能無法呼叫所請求的模型；請至模型市場確認該模型對你可用 |
| 404 Not Found | 資源不存在 | 通常是模型 ID 拼錯；請從模型市場複製完全一致的 ID |
| 429 Too Many Requests | 觸發速率限制 | 請求過於頻繁。請退避重試（指數級間隔）或降低併發數；若持續發生請聯絡平台 |
| 5xx | 伺服器端錯誤 | 平台或上游模型的暫時性故障。以相同參數重試一次；若持續失敗，請附上日誌頁中該次請求的記錄聯絡支援 |
排查步驟
- 確認金鑰：在「API 金鑰」頁確認金鑰存在且未過期；不確定時刪除後重新建立。
- 確認模型 ID：從模型市場複製，不要手動輸入。
- 讀取錯誤內容：錯誤回應通常會帶
error.message，說明確切原因（餘額不足、缺少參數……）。 - 查看日誌：控制台日誌頁顯示每次請求的狀態、延遲與消耗——確認失敗是否只限於某個模型或某把金鑰。
- 仍然卡住：附上日誌頁中的時間戳與狀態碼，聯絡支援。
減少報錯的做法
- 使用官方 SDK（它會替你處理重試、逾時與協議細節）；
- 針對 429 / 5xx 實作指數退避，而不是硬重試；
- 為正式金鑰設定消費上限，避免異常流量把餘額消耗殆盡。