錯誤代碼與疑難排解

確認失敗環節

1. 記錄實際 HTTP 狀態、請求方法與路徑。HTTP 狀態與應用程式錯誤代碼描述不同層次，請勿互相替代。
2. 依呼叫的協定讀取錯誤欄位。原生、OpenAI、Claude 與 Gemini 回應並非都具有相同結構。
3. 串流請求也要檢查錯誤事件與完成狀態；非同步任務則檢查任務 status。HTTP 200 不保證生成成功。
4. 使用下表修正請求或決定是否重試。message 是說明文字，不是穩定列舉值，請勿依措辭分支處理。

平台錯誤代碼列舉

以下是平台應用程式錯誤代碼的完整列舉。名稱供參考，回應的 code 值是數字。「常見 HTTP」是排查指引，不是所有端點的固定對應，請以實際 HTTP 狀態與回應主體為準。由上游透傳的 code 可能不屬於此列舉。

單憑 HTTP 429 無法可靠區分速率限制與並行限制，僅在有明確數字錯誤代碼時才做區分。請在模型清單核對模型識別碼，勿自行改寫 model 值。

依協定讀取錯誤

以下範例展示平台常見的錯誤結構，不保證每次失敗都採用單一格式。驗證失敗可能由不同處理層回傳，上游透傳回應也可能保留自己的結構、字串代碼或類型。解析前先辨識實際回應結構；若無法辨識，請保留原始欄位與 HTTP 狀態，不要強制轉換。

原生平台 API

通常讀取 error.code 與 error.message。requestId 可能不存在。

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

部分錯誤可能使用頂層 code 與 message。客戶端應容忍此差異，不得將缺少 error 物件當成成功證據。參數驗證回應也可能沒有數字錯誤代碼；缺少代碼應視為未知，不要自行編造。

OpenAI 相容 API

平台常見錯誤使用頂層 code、message 與 type，不一定包在 error 中。

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type 是協定分類；在此結構中，code 是平台數字錯誤代碼。單憑 api_error 不能決定是否適合重試。上游透傳與串流錯誤可能包含巢狀 error，請處理實際協定回應。詳見 Chat Completions 與 Responses。

Claude 相容 API

常見結構中的頂層 type 為 error，具體分類在 error.type，說明在 error.message。此結構不包含平台數字 code，請勿編造。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

平台在本機產生下列 Claude 錯誤類型。這不是上游所有錯誤類型的完整列舉。

詳見 Claude 訊息。

Gemini 風格錯誤

收到 Gemini 風格回應時，請讀取 error.code、error.message 與 error.status。此處 status 是字串分類，不是 HTTP 狀態或非同步任務狀態。

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

平台產生的此類結構使用平台數字 code 值。下表是本機字串 status 對應，不是所有上游狀態的列舉。

503 優先使用 UNAVAILABLE，而非 INTERNAL。上游回應的 code 與 status 可能有不同語義，請勿將平台錯誤代碼表套用到每個 Gemini 數字代碼。

安全重試

若有有效的 Retry-After 標頭，請遵循它；不要假設每個錯誤都有此標頭。自動重試非冪等生成請求可能再次執行並產生額外費用。本頁不承諾通用冪等鍵支援，自行加入 Idempotency-Key 不保證去重。

若已有 jobId，請先查詢該任務再建立新任務。若沒有 jobId 且結果不明，請保留請求識別碼與時間戳記以供調查。

串流與非同步任務

SSE 請求

SSE 開始後，HTTP 狀態可能維持 200，而後續失敗透過串流內錯誤事件或承載資料回報。請依所選協定解析事件與資料，確認正常完成。發生錯誤或非預期斷線時，不得將部分文字或圖像視為完整成功結果。不同端點的事件名稱與承載資料不同，請勿只檢查單一固定 error 欄位，也不要以「收到任何文字」作為成功條件。

非同步任務

建立回應包含 data.jobId 代表請求已受理，不代表生成完成。查詢任務時 HTTP 回應成功只代表查詢成功，仍必須檢查任務的 data.status：

• PENDING、CONNECT、PROCESSING：依 Jobs 文件繼續輪詢。
• COMPLETED：讀取 outputResult。
• FAILED、CANCELLED：停止輪詢，保留任務 ID 與已脫敏回應資訊以供調查。

失敗詳情可能出現在 data.outputResult.error。此欄位是選填，不保證每個失敗任務都有。只有建立回應明確傳回 jobId 時才使用 Jobs。直接透過 JSON 或 SSE 傳回結果的端點不應套用任務輪詢。

提供給使用者與 AI 助手的診斷資訊

向支援人員或 AI 助手提供下列已脫敏資訊。缺少的欄位使用 unknown；若未收到 HTTP 回應，HTTP 狀態也使用 unknown。請保留欄位路徑與原始值類型，例如 error.code: 10000 (number) 或 error.code: "invalid_api_key" (string)。不要自動將字串 code 轉成平台數字代碼，也不要從 message、HTTP 狀態或模型名稱編造缺少的欄位。

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

可用時，從回應主體或 X-Request-ID 回應標頭讀取 requestId。保留字串形式的 jobId，避免長數字精度流失。只提供最少且已脫敏的請求參數。移除 API 金鑰、token、cookie、完整驗證標頭、個人資訊、私密提示詞與輸入檔案內容。移除網址查詢參數，以及含簽章或存取憑證的輸入／輸出網址。未檢查前請勿貼上完整請求日誌。

AI 助手應區分已觀察欄位與可能原因，並指出缺少的資訊。證據不足不得視為請求成功、未執行或未產生費用的證明。