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

錯誤與復原

瞭解 Agents API 錯誤及安全復原的方法。

關於一般 HTTP 錯誤和 SDK 例外狀況,請參閱通用的錯誤碼指南。

檢查錯誤

如果請求失敗,請檢查 HTTP 回應。如果在回合執行或環境設定期間發生錯誤,請檢查事件和已儲存的狀態。

失敗類型 檢查方式
API 請求 查看 HTTP 狀態碼和回應中的 error 物件。
回合 收到 agent.session.turn.failed 時,取得回合,並檢查 status 和 error。
工作階段 收到 agent.session.failed 時,取得工作階段,並檢查 status 和 error。
環境 查看 environment.error 欄位,其位於 agent.session.environment.failed 事件中。請參閱沙盒疑難排解。

對於結構化錯誤,請在應用程式邏輯中使用 error.code 判斷如何處理,並使用 error.message 說明失敗原因。若請求未通過驗證,error.param 可能會指出需要修正的欄位。請確保錯誤處理程式遇到未知的錯誤碼或缺少 param 時仍能正常運作。

在 Beta 版 API(OpenAI-Beta: agents=v1)中,工作階段的 error 是訊息字串或 null。若要取得工作階段失敗的錯誤碼,請查看一併傳送的 SSE error 事件。

API 請求錯誤

這些錯誤說明傳送給 Agents API 的請求出了什麼問題,與工作開始後傳回的回合錯誤不同。

錯誤碼 說明
400:invalid_request_error 原因: 輸入值或設定值無效或過大。
處理方式: 修正 error.param 或 error.message 指出的欄位。請參閱修正無效輸入。
400:invalid_beta 原因: OpenAI-Beta 標頭含有無效值。
處理方式: 確認所用 API 版本要求的標頭值。
400:agent_not_persisted 原因: 提供的 agent_id 屬於僅在該工作階段內可用的智慧體。
處理方式: 建立並儲存可跨工作階段使用的智慧體,並使用其 ID。
400:invalid_otlp_endpoint、invalid_otlp_header 原因: 追蹤端點或標頭無效。
處理方式: 修正追蹤設定。
401:unauthorized;403:forbidden 原因: 驗證失敗,或呼叫端缺少存取權限。
處理方式: 請參閱通用的驗證與權限指南。
404:not_found_error、model_not_found 原因: 此請求無法使用指定的資源或模型。
處理方式: 檢查 ID、模型和專案,並確認資源是否已刪除。
409:conflict_error 原因: 操作與資源的目前狀態衝突。
處理方式: 先查看錯誤訊息並取得資源的目前狀態,再重試。
409:executor_version_incompatible 原因: 系統不支援此執行器版本。
處理方式: 升級執行器後再重試。
424:mcp_server_startup_failed 原因: MCP 伺服器啟動失敗。
處理方式: 檢查伺服器的設定和憑證。請參閱排解連線問題。
429:files_api_rate_limit_exceeded 原因: 檔案請求超出 Files API 對該使用者的速率限制。
處理方式: 減少同時發出的請求,並依照 Files API 速率限制指引處理。
500:internal_error 原因: 服務發生非預期的錯誤。
處理方式: 重試前先檢查已儲存的工作。請參閱通用的伺服器錯誤指南。
503:service_unavailable_error、server_is_overloaded 原因: 服務或其依賴項目暫時無法使用或負載過高。
處理方式: 依照通用的 503 錯誤指引處理,並在重試前檢查已儲存的工作。

Files API 速率限制

建立工作階段或附加檔案的請求可能會傳回 HTTP 429,並附上 files_api_rate_limit_exceeded 錯誤碼。Agents API 會透過 Files API 檢查檔案。這些檢查會占用已驗證使用者的 Files API 配額,每個附加檔案都可能需要單獨檢查。

{
  "error": {
    "type": "rate_limit_error",
    "code": "files_api_rate_limit_exceeded",
    "message": "The Files API rate limit for your user has been exceeded. Reduce the rate of requests that access files, then try again.",
    "param": null
  }
}

減少同時存取檔案的請求數量。重試時採用指數退避策略,並設定嘗試次數上限。立即重試可能會持續耗盡配額。

此 HTTP 回應表示操作已失敗。另一種情況是建立請求傳回成功回應後,工作階段或回合才以非同步方式失敗。若要辨識這項速率限制錯誤,請檢查 error.code,避免以訊息文字進行比對。

回合錯誤

回合失敗時,狀態為 status: "failed",且 error 包含 code 和 message。例如,模型負載過高時可能會傳回:

{
  "code": "server_overloaded",
  "message": "The model is temporarily overloaded. Please retry your request after a brief delay."
}

回合錯誤碼本身沒有對應的 HTTP 狀態碼。例如,回合失敗時使用 server_overloaded,HTTP 回應則可能使用 server_is_overloaded。

錯誤碼 說明
invalid_request 原因: 輸入或設定無效。
處理方式: 修正錯誤訊息指出的輸入後再重試。
context_length_exceeded 原因: 輸入超出模型的上下文視窗。
處理方式: 縮短輸入。如果對話過長,請用較短的摘要開始新的工作階段。
session_budget_exceeded 原因: 工作階段已用盡用量預算。
處理方式: 建立新的工作階段以繼續。
credit_balance_exhausted 原因: 組織的 API 點數已用完。
處理方式: 請參閱點數餘額指引。
project_spend_limit_exceeded 原因: 專案已達強制執行的支出上限。
處理方式: 請參閱專案支出上限指引。
organization_spend_limit_exceeded 原因: 組織已達強制執行的支出上限。
處理方式: 請參閱組織支出上限指引。
organization_usage_limit_exceeded 原因: 組織已達 OpenAI 為其設定的用量上限。
處理方式: 請參閱組織用量上限指引。
usage_limit_exceeded 原因: 已達計費或用量上限,且沒有更具體的錯誤碼。
處理方式: 依照通用的計費錯誤指引處理。
rate_limit_exceeded 原因: 請求超出適用的速率限制。
處理方式: 依照重試步驟處理。
server_overloaded 原因: 模型服務暫時負載過高。
處理方式: 稍候再重試未完成的工作。如果負載持續過高,請為後續回合改用其他模型。
flex_unavailable 原因: Flex 處理暫時無法使用。
處理方式: 稍後再試,或變更工作階段的服務層級,讓後續回合使用標準處理(default)。
connection_failed、request_timeout、server_error、internal_error 原因: 連線失敗、請求逾時或服務故障,導致回合無法完成。
處理方式: 檢查已儲存的工作,再設定嘗試次數上限並重試。
authentication_error 原因: 因憑證或權限問題而無法存取模型。
處理方式: 請參閱通用的驗證與權限指南。
resource_not_found 原因: 要求的模型或資源無法使用。
處理方式: 重試前先檢查模型和工作階段設定。
sandbox_error 原因: 環境無法完成操作。
處理方式: 檢查環境錯誤,並修正設定或連線問題。
executor_version_incompatible 原因: 執行器無法執行此回合。
處理方式: 升級執行器。如果工作階段尚未失敗,請在同一個工作階段重試。
active_turn_not_steerable 原因: 目前執行中的回合無法接收更多輸入。
處理方式: 等待回合結束後再傳送下一則訊息。
cyber_policy、misalignment_policy_violation 原因: 安全系統封鎖了請求。
處理方式: 依照適用的安全要求檢視請求,再提交修正後的輸入。

工作階段與環境錯誤

回合失敗時,工作階段仍有可能繼續。請取得工作階段並確認是否可以繼續使用。如果 status 為 requires_action,請處理該工作階段的必要動作。如果工作階段已失敗,請排除失敗原因,再使用仍需要的輸入建立新的工作階段。

錯誤碼 說明
environment_connection_failed、environment_connection_timeout 原因: 沙盒無法連線,或建立連線所需的時間過長。
處理方式: 檢查執行器是否已啟動,以及能否存取網路。如果是自行託管的環境,請檢查連線設定。
sandbox_error 原因: 沙盒設定或執行失敗。
處理方式: 檢查設定指令、套件、輸入檔案和環境錯誤。
executor_version_incompatible 原因: 系統不支援此工作階段的執行器版本。
處理方式: 建立新的工作階段前,請先升級執行器。
idle_timeout 原因: 託管環境因閒置而到期。
處理方式: 建立新的工作階段,並再次提供輸入。
internal_error 原因: 內部錯誤導致工作階段或環境無法進入就緒狀態。
處理方式: 稍候再重試設定。如果持續失敗,請聯絡支援團隊。

復原

暫時性錯誤的重試步驟

遇到速率限制、負載過高、逾時或暫時性服務故障時,請依照下列步驟處理。如果問題涉及無效輸入、憑證或計費上限,請先排除問題再重試。

  1. 確認執行結果。 如果已建立工作階段,請取得該工作階段、回合和已儲存的項目。如果回合仍在執行,請繼續追蹤其進度。如果回合已完成,請使用其結果。
  2. 檢查已完成的動作。 即使回合失敗,也可能已變更檔案或呼叫外部工具。請先確認這些動作造成的影響,再要求智慧體重做。
  3. 等候一段時間,並限制重試次數。 請依照通用的重試指引,按 HTTP 回應中 Retry-After 指定的時間等候,並設定嘗試次數上限或截止時間。
  4. 重試請求或開始新的回合。 如果發生 HTTP 錯誤,請先確認原操作的結果,再重試該操作。如果回合失敗,請等到工作階段進入 idle 狀態,再傳送後續訊息,要求智慧體只繼續執行未完成的工作。這會在現有對話中開始新的回合。

即使回合已完成,也請檢查工具結果。如果錯誤改變或已達重試次數上限,請停止自動重試。

修正無效輸入

請修正 error.param 或 error.message 指出的欄位,再重新提交。

如果錯誤與大小有關,請先縮減輸入和輸出結構描述或工具結果的大小,再重試。如果智慧體設定過大,請精簡指令和工具定義,再用來建立新的工作階段。

如需上傳要求和範例,請參閱排解上傳錯誤。如果錯誤訊息指出圖片有問題,請檢查圖片資料或 URL。

串流中斷

收到 error 事件或串流中斷時,仍無法確定回合的最終狀態。請依照恢復中斷的串流的步驟重新連線,並在重新提交輸入前檢查已儲存的工作。如果取得的工作階段顯示 status: "failed",或收到 agent.session.failed 事件,請停止嘗試重新連線,並依照工作階段復原指引處理。

如果錯誤持續發生,請在向支援團隊求助時附上請求 ID、工作階段 ID 和回合 ID。