常見錯誤與疑難排解

在呼叫 API 遇到錯誤時，可以透過返回的 HTTP 狀態碼與回應本體中的 error.message 快速定位原因。

---

常見 HTTP 狀態碼清單

1. 401 Unauthorized (認證失敗 / 無效金鑰)

典型回應：

{
  "error": {
    "message": "Incorrect API key provided: sk-***",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

排查清單：

• 檢查請求標頭 Authorization: Bearer sk-... 格式是否規範，金鑰前後是否有誤複製的空格或換行。
• 在「控制台 - API 金鑰」中檢查該權杖是否已被停用或刪除。
• 確認目前使用的權杖是否設定了 IP 白名單或限定了模型範圍。

---

2. 429 Too Many Requests / Insufficient Quota (超額 / 頻率限制)

可能原因與解決方案：

1. 帳戶或權杖額度耗盡（Insufficient Quota）：
   • 檢查「個人控制台」總帳戶餘額。
   • 檢查目前使用的 API Key 是否設定了獨立的額度上限且已達上限。
2. 請求頻率或並行超限（Rate Limit Exceeded）：
   • 用戶端短時間內發起突發高並行請求。
   • 建議在用戶端程式碼中實作指數退避重試（Exponential Backoff）。如需更高企業並行量，請在支援中心提交工單。

---

3. 404 Model Not Found (模型不存在)

可能原因與解決方案：

• 請求本體中的 model 欄位名稱拼寫有誤（如將 gpt-4o 誤寫為 gpt4o）。
• 確認該模型在平台目前處於可用狀態（可在 模型廣場 查看）。

---

4. 500 / 502 / 504 Gateway Error (上游通道異常)

可能原因與解決方案：

• 上游模型官方提供商（如 OpenAI、Anthropic）發生服務中斷或網路波動。
• Ainfix 內建了多通道智慧重試與自動 Failover 機制，絕大部分網路抖動會在平台內部完成無感轉移；若大範圍持續報錯，請關注平台狀態或在支援中心發起工單。