如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

錯誤碼

瞭解 API 錯誤碼及其解決方法。

本指南整理了使用 API 和官方 Python 函式庫時可能遇到的錯誤碼。各錯誤碼的專節提供更詳細的處理指引。

API 錯誤

錯誤碼 說明
400 - service_tier 引數無效 原因: 專案不允許請求指定或系統最終選用的服務層級。
解決方法: 將 service_tier 設為專案允許的層級,或在專案設定中更新允許的服務層級。
401 - 身分驗證無效 原因: 身分驗證無效。
解決方法: 確認請求使用正確的 API 金鑰,且發出請求的組織正確。
401 - 提供的 API 金鑰不正確 原因: 請求使用的 API 金鑰不正確。
解決方法: 確認使用的 API 金鑰正確、清除瀏覽器快取,或產生新金鑰。
401 - 必須是組織成員才能使用 API 原因: 你的帳戶不屬於任何組織。
解決方法: 聯絡我們,請我們將你加入新組織,或請組織管理員邀請你加入組織。
401 - IP 位址未獲授權 原因: 請求的來源 IP 位址不在專案或組織設定的 IP 允許清單中。
解決方法: 從正確的 IP 位址傳送請求,或更新 IP 允許清單設定。
403 - 不支援所在國家、地區或領土 原因: 你正從不受支援的國家、地區或領土存取 API。
解決方法: 詳情請參閱支援的國家和地區。
429 - 點數已用完 代碼: credit_balance_exhausted
原因: 組織已用完預付點數。
解決方法: 加值點數即可繼續使用 API。
429 - 已達請求速率限制 原因: 傳送請求的頻率過高。
解決方法: 控制傳送請求的頻率。如果回應包含 Retry-After 標頭,請依照標頭指定的時間等候。請參閱速率限制指南。
429 - 請降低速率 類型: rate_limit_error
代碼: slow_down
原因: 請求速率上升過快。
解決方法: 如果回應包含 Retry-After 標頭,請依照標頭指定的時間等候。先降低請求速率,再逐步提高。
429 - 已達組織支出上限 代碼: organization_spend_limit_exceeded
原因: 組織已達目前生效的支出上限。
解決方法: 提高或移除組織支出上限。
429 - 已達專案支出上限 代碼: project_spend_limit_exceeded
原因: 專案已達目前生效的支出上限。
解決方法: 在專案設定中提高或移除支出上限。
429 - 已達組織用量上限 代碼: organization_usage_limit_exceeded
原因: 組織已達 OpenAI 核定的用量上限。
解決方法: 申請提高核准的用量上限,或聯絡支援團隊。
500 - 伺服器處理請求時發生錯誤 原因: 我們的伺服器發生問題。
解決方法: 稍候再重試請求。如果問題持續發生,請聯絡我們。你可以查看系統狀態頁面。
503 - 模型暫時超載 類型: service_unavailable_error
代碼: server_is_overloaded
原因: 請求的模型暫時超載。
解決方法: 如果回應包含 Retry-After 標頭,請依照標頭指定的時間等候,再重試請求。

遇到帳務相關錯誤時,請檢查 error.code 以判斷具體原因。較廣義的 error.type 仍可能是 insufficient_quota。

遇到帳務、支出或配額錯誤時,重試請求無法恢復 API 存取權。請先加值點數或調整相關上限,再傳送請求。

WebSocket 模式錯誤

使用 Responses API 的 WebSocket 模式時,還可能遇到下列錯誤:

  • previous_response_not_found:系統無法根據目前可用的狀態找到 previous_response_id 對應的回應。請提供完整的輸入上下文,並將 previous_response_id 設為 null 後重試。
  • websocket_connection_limit_reached:連線時間已達 60 分鐘上限。請建立新的 WebSocket 連線後繼續。

Python 函式庫錯誤類型

Python 函式庫引發的 RateLimitError 對應 429 回應,InternalServerError 則對應 503 回應。如果你的錯誤處理程式先前只捕捉其中一種例外來處理限流和超載,請改為處理兩種例外,並檢查 error.code。例如,影片端點超載時,現在會傳回 503,先前則是傳回 429。各端點的變更請參閱遷移指南。

類型 說明
APIConnectionError 原因: 連線至我們的服務時發生問題。
解決方法: 檢查網路設定、Proxy 設定、SSL 憑證或防火牆規則。
APITimeoutError 原因: 請求逾時。
解決方法: 稍候再重試請求。如果問題持續發生,請聯絡我們。
AuthenticationError 原因: API 金鑰或權杖無效、已過期或已撤銷。
解決方法: 檢查 API 金鑰或權杖,確認內容正確且仍有效。你可能需要從帳戶儀表板產生新的金鑰或權杖。
BadRequestError 原因: 請求格式有誤,或缺少權杖、輸入內容等必要參數。
解決方法: 錯誤訊息通常會指出具體問題。請查看所呼叫 API 方法的文件,確認傳送的參數有效且完整。你可能也需要檢查請求資料的編碼、格式或大小。
ConflictError 原因: 另一個請求已更新該資源。
解決方法: 再次嘗試更新資源,並確認沒有其他請求同時嘗試更新。
InternalServerError 原因: 我們的系統發生問題。
解決方法: 稍候再重試請求。如果問題持續發生,請聯絡我們。
NotFoundError 原因: 請求的資源不存在。
解決方法: 確認使用的資源識別碼正確。
PermissionDeniedError 原因: 你沒有存取所請求資源的權限。
解決方法: 確認使用的 API 金鑰、組織 ID 和資源 ID 正確。
RateLimitError 原因: 你已達獲配的速率限制,或流量增加過快。
解決方法: 控制傳送請求的頻率。如果回應包含 Retry-After,請依照指定時間等候,並遵守重試次數限制。詳情請參閱速率限制指南。
UnprocessableEntityError 原因: 請求格式正確,但系統無法處理。
解決方法: 請重試請求。

持續發生的錯誤

如果問題持續發生,請透過對話聯絡支援團隊,並提供下列資訊:

  • 你使用的模型
  • 收到的錯誤訊息和錯誤碼
  • 傳送的請求資料和標頭
  • 發出請求的時間戳記和時區
  • 其他有助於診斷問題的相關細節

支援團隊會調查問題並儘快回覆你。由於支援需求量大,等候回覆的時間可能較長。你也可以在社群論壇發文,但請務必移除所有敏感資訊。

處理錯誤

建議在程式中處理 API 傳回的錯誤。你可以參考下列程式碼片段:

import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-6-astra",
    input: "Hello world",
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("Failed to connect to the OpenAI API:", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("OpenAI API request exceeded its rate limit:", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API returned an error:", error.status, error.message);
  } else {
    throw error;
  }
}