AI API 疑難排解
本頁整理 LLMPool AI API 的常見錯誤、原因及處理方法。請先確認使用正確協議：
- OpenAI 相容 Base URL：
https://api.benpay.ai/openai/v1 - Anthropic 相容 Base URL：
https://api.benpay.ai/anthropic/v1
錯誤欄位說明請參閱錯誤回應。請先按 HTTP 狀態碼判斷類別，再使用 OpenAI error.code 或 Anthropic error.type。不要依賴 message 文字作程式判斷。
建議排查次序
- 記錄 HTTP 狀態碼、請求路徑及回應 Header 的請求識別碼；切勿記錄密鑰或完整請求內容。
- 即使 HTTP 為非
2xx，亦先判斷內容是否為有效業務物件，例如帶status: "failed"的 Response。 - OpenAI 按 HTTP 及
error.code定位；Anthropic 按 HTTP 及error.type定位。 - 按下表修正請求、聯絡平台支援或有限重試。重試前確認操作可安全重放。
驗證及存取
OpenAI error.code | Anthropic error.type | HTTP | 自動重試 | 原因 | 解決方法 |
|---|---|---|---|---|---|
invalid_api_key | authentication_error | 401 | 否 | API 密鑰缺失、格式錯誤、無效、過期、停用、未綁定帳戶，或帳戶無法使用 | 確認 Header 及 Base URL；在 Dashboard 的 API 密鑰頁面檢查狀態 |
ip_not_allowed | authentication_error，並帶 error.code=ip_not_allowed | 403 | 否 | 來源 IP 不在白名單，或代理未傳遞預期 IP | 檢查 IP 白名單、出口 IP 及反向代理設定 |
OpenAI 使用：
Authorization: Bearer YOUR_API_KEY
Anthropic 優先使用：
x-api-key: YOUR_API_KEY
Anthropic 亦接受 Bearer Token；同時提供時以 x-api-key 為準。
餘額及計費
OpenAI error.code | Anthropic error.type | HTTP | 自動重試 | 原因 | 解決方法 |
|---|---|---|---|---|---|
insufficient_wallets | invalid_request_error，沒有獨立標識 | 402 | 否 | 可用錢包及訂閱餘額不足 | 前往 Dashboard 增值或聯絡組織負責人 |
meter_price_rules_error | 不適用 | 400 或 500 | 否 | 計量規則缺失、不完整或讀取失敗 | 轉換模型或聯絡平台支援；原樣重試無效 |
請求及參數
OpenAI error.code | Anthropic error.type | HTTP | 自動重試 | 原因 | 解決方法 |
|---|---|---|---|---|---|
invalid_request | invalid_request_error | 400 | 否 | JSON、Content-Type 或框架解析失敗 | 檢查 JSON、欄位類型及必填欄位 |
invalid_request_error | invalid_request_error | 400 或 422 | 否 | 上游拒絕參數組合 | 檢查模型支援的參數及內容類型 |
missing_model | invalid_request_error | 400 | 否 | 沒有 model 或模型名稱為空 | 使用 模型頁面所列的 Product ID |
context_length_exceeded | invalid_request_error | 400 | 否 | 輸入及預期輸出超出上下文視窗 | 縮短歷史、附件或最大輸出 Token |
conversion_error | 不適用 | 400 | 否 | Chat Completions 無法轉換為 Responses 請求 | 簡化輸入及移除不支援欄位 |
request_too_large | request_too_large | 413 | 否 | HTTP 請求內容超出限制 | 減少文字、圖片或檔案大小 |
method_not_allowed | invalid_request_error | 405 | 否 | HTTP 方法錯誤 | 使用 API 文件指定的方法 |
not_found | not_found_error | 404 | 否 | 路徑或資源不存在 | 檢查 Base URL、版本路徑及資源 ID |
模型及路由
OpenAI error.code | Anthropic error.type | HTTP | 自動重試 | 原因 | 解決方法 |
|---|---|---|---|---|---|
invalid_model | invalid_request_error | 400 | 否 | 模型 ID 為空或格式無效 | 從 模型頁面複製 Product ID |
model_not_found | not_found_error | 404 | 否 | 找不到 Product | 檢查拼寫及模型是否仍可見 |
model_not_supported | invalid_request_error | 400 | 否 | Product 不支援目前協議或功能 | 選擇支援該操作的模型或 API |
service_unavailable | overloaded_error | OpenAI 503 / Anthropic 529 | 是 | 現時沒有可用模型或容量 | 退避重試或轉換模型 |
模型出現在目錄只代表客戶端可發現它，不保證現時有推理容量。
限流
OpenAI error.code | Anthropic error.type | HTTP | 自動重試 | 原因 | 解決方法 |
|---|---|---|---|---|---|
rate_limit_exceeded | rate_limit_error | 429 | 是 | IP、API 密鑰、平台或上游限流 | 遵從 Retry-After，使用指數退避並減少並行請求 |
rate_limited | rate_limit_error | 429 | 是 | 模型的所有候選上游都受限 | 退避重試或轉換模型 |
建議由約 1s 開始，每次加倍並加入隨機抖動，同時設定最大重試次數及總逾時。
上游服務
OpenAI error.code | Anthropic error.type | HTTP | 自動重試 | 原因 | 解決方法 |
|---|---|---|---|---|---|
upstream_configuration_error | api_error | OpenAI 502 / Anthropic 500 | 否 | 上游憑證、模型映射或平台設定錯誤 | 聯絡平台支援 |
upstream_unavailable | api_error | 502 | 是 | 上游連線失敗或暫時無法使用 | 退避重試，必要時轉換模型 |
upstream_timeout | api_error | 504 | 是 | 上游未在限時內回應 | 退避重試或縮短上下文 |
| 不適用 | overloaded_error | 529 | 是 | Anthropic 相容上游過載 | 退避重試或轉換模型 |
內部錯誤
OpenAI error.code | Anthropic error.type | HTTP | 自動重試 | 原因 | 解決方法 |
|---|---|---|---|---|---|
internal_error | api_error | 500 | 有限 | 資料庫、映射、解密或其他內部處理失敗 | 稍候有限重試；持續出現時聯絡支援 |
file_service_error | 不適用 | 500 | 有限 | 圖片或附件內部處理失敗 | 檢查附件格式及大小後重試 |
response_conversion_error | 不適用 | 500 | 有限 | 上游回應無法轉換為 Responses 物件 | 有限重試或轉換模型 |
串流中斷
如果串流已開始，HTTP 狀態可能仍為 200，其後才收到 stream_error 或 Anthropic event: error。
- 立即結束串流，切勿把片段當作完整結果。
- 記錄錯誤類型及本機請求時間，切勿記錄密鑰或敏感內容。
- 確認操作可安全重試後，再使用退避策略重新請求。
- 持續發生時轉換模型並聯絡支援。
事件結構請參閱錯誤回應。
常見情況
持續收到 401
- 確認使用 LLMPool OpenAI 或 Anthropic Base URL，而非 Dashboard 地址。
- 切勿把 Admin Token 或 Tenant Access Token 當作 AI API 密鑰。
- 重新複製密鑰，檢查空格及 Header 格式。
- 在 Dashboard 檢查密鑰是否過期或停用。
404 找不到模型
- 從 模型頁面複製模型名稱。
- 使用 Product ID，切勿使用供應商內部 fullname。
- 確認協議及操作符合模型能力。
經常收到 429、5xx 或 529
- 減少並行請求，遵從
Retry-After並加入隨機抖動。 - 只作有限次數的退避重試，並嘗試其他模型。
- 記錄時間、協議、路徑、HTTP 狀態、結構化錯誤及 Product ID。
- 持續出現或多個模型同時失敗時聯絡支援。
聯絡支援
請提供發生時間及時區、協議、請求路徑及方法、HTTP 狀態碼、結構化錯誤類型、Product ID、是否為串流請求，以及回應 Header 的請求識別碼。
切勿提供完整 API 密鑰、請求內容、GraphQL 文件及變數、檔案內容，或含查詢參數的完整 URL。