AI API 錯誤回應

LLMPool 的 OpenAI 相容及 Anthropic 相容介面使用各自協議的錯誤格式。應用程式應先檢查 HTTP 狀態碼，再讀取協議相應的結構化錯誤欄位。

錯誤訊息只供人員閱讀，並非穩定的程式契約。請勿配對 message 文字來決定重試或業務分支。

OpenAI 相容格式

{
  "error": {
    "message": "The requested model was not found.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

欄位	類型	說明
`error.message`	string	供開發者閱讀的安全錯誤說明
`error.type`	string	OpenAI 相容錯誤類別
`error.param`	string 或 null	與錯誤有關的請求欄位
`error.code`	string 或 null	可供程式判斷的具體錯誤碼

程式處理時應優先使用 HTTP 狀態碼及 error.code。

Anthropic 相容格式

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested model was not found."
  }
}

欄位	類型	說明
`type`	string	錯誤回應固定為 `error`
`error.type`	string	Anthropic 相容錯誤類別
`error.message`	string	供開發者閱讀的安全錯誤說明
`error.code`	string 或省略	只在部分錯誤提供，例如 `ip_not_allowed`

Anthropic 客戶端應主要按 HTTP 狀態碼及 error.type 處理錯誤。

欄位來源

內容	主要來源	客戶端處理方式
HTTP 狀態碼	LLMPool 按故障類別標準化；少數協議直通回應保留上游狀態碼	按下表分類處理
OpenAI `error.code`	LLMPool 定義的常見錯誤碼	可配合 HTTP 狀態碼作程式判斷
OpenAI `error.type` / Anthropic `error.type`	LLMPool 映射為協議相容類型；直通回應可能來自上游	只依賴文件明確列出的類型
`error.message`	標準錯誤使用安全文案；直通回應可能保留上游文案	只用於顯示、記錄及人工排查

非 2xx 業務回應例外

少數相容上游會為結構正確的業務回應附加非 2xx 狀態。LLMPool 確認內容符合目標端點後，可能保留該狀態並傳回業務物件：

Chat Completions 及 Responses 可傳回有效的 OpenAI 業務物件。
Anthropic 非串流 Messages、Files 及 Message Batches 可傳回有效的 Anthropic 業務物件。
Responses 物件可帶有 status: "failed"，同時保留正常結構及用量資料。

客戶端遇到非 2xx 時，應先判斷內容是否為目標端點的業務物件，再解析錯誤 envelope。

常見 HTTP 狀態碼

狀態碼	含義	預設處理方式
`400`	請求、參數、模型能力或上下文長度無效	修正請求後再提交
`401`	API 密鑰無效	檢查密鑰及驗證 Header，請勿自動重試
`402`	帳戶餘額不足	增值後再提交
`403`	API 密鑰不允許來源 IP	檢查 IP 白名單
`404`	找不到模型、回應或其他資源	檢查 ID 及請求路徑
`405`	不支援 HTTP 方法	使用文件指定的方法
`413`	請求內容過大	減少內容或附件大小
`422`	JSON 有效，但參數組合無效	修正請求後再提交
`429`	平台或上游限流	遵從 `Retry-After` 並退避重試
`500`	LLMPool 內部錯誤；Anthropic 亦可能表示上游設定錯誤	按結構化類型判斷
`502`	上游設定錯誤或暫時無法使用	按 `error.code` 判斷是否重試
`503`	OpenAI 相容模型現時沒有可用容量	退避重試或轉換模型
`504`	上游請求逾時	退避重試，必要時縮短輸入
`529`	Anthropic 相容上游或模型過載	退避重試或轉換模型

詳情請參閱疑難排解。

串流錯誤

串流請求可能在 HTTP 200 及回應標頭送出後才發生錯誤。客戶端必須繼續解析 SSE 事件。

Chat Completions

{
  "error": {
    "message": "Upstream stream interrupted.",
    "type": "server_error",
    "param": null,
    "code": "stream_error"
  }
}

Responses API

{
  "type": "error",
  "code": "stream_error",
  "message": "Upstream stream interrupted.",
  "param": null,
  "sequence_number": 7
}

Responses API 亦可能收到有效的 response.failed 終態：

{
  "type": "response.failed",
  "sequence_number": 7,
  "response": {
    "id": "resp_123",
    "object": "response",
    "status": "failed",
    "error": {
      "code": "server_error",
      "message": "The response failed."
    }
  }
}

response.failed 是 Responses 協議的業務終態。LLMPool 會轉發該事件並結束串流，不會再加入合成錯誤。客戶端須同時處理 type: "error" 及 type: "response.failed"。

Anthropic Messages

Anthropic Messages 使用 SSE event: error：

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "Upstream stream interrupted."
  }
}

收到串流錯誤或失敗終態後應結束目前串流，切勿把已收到的片段當作完整回應。

重試原則

400、401、402、403、404、405、413 及 422 通常須先修正請求或帳戶狀態。
429 rate_limit_exceeded、429 rate_limited、502 upstream_unavailable、503 service_unavailable、504 upstream_timeout 及 529 overloaded_error 可使用帶隨機抖動的指數退避。
502 upstream_configuration_error 及 400/500 meter_price_rules_error 屬平台設定問題，原樣重試通常無效。
500 internal_error 或 Anthropic 500 api_error 只應有限重試；持續發生時請聯絡支援。
優先遵從 Retry-After Header。
建立資源、Batch 等非冪等操作在重試前須確認首次請求是否成功。
所有自動重試都應設上限及總逾時時間。

LLMPool 不會在標準錯誤中傳回上游原始回應、憑證、內部模型名稱、API Base 或代理地址。聯絡支援時也請勿提供完整 API 密鑰、請求內容或檔案內容。