關於一般 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 |
原因: 內部錯誤導致工作階段或環境無法進入就緒狀態。 處理方式: 稍候再重試設定。如果持續失敗,請聯絡支援團隊。 |
復原
暫時性錯誤的重試步驟
遇到速率限制、負載過高、逾時或暫時性服務故障時,請依照下列步驟處理。如果問題涉及無效輸入、憑證或計費上限,請先排除問題再重試。
- 確認執行結果。 如果已建立工作階段,請取得該工作階段、回合和已儲存的項目。如果回合仍在執行,請繼續追蹤其進度。如果回合已完成,請使用其結果。
- 檢查已完成的動作。 即使回合失敗,也可能已變更檔案或呼叫外部工具。請先確認這些動作造成的影響,再要求智慧體重做。
- 等候一段時間,並限制重試次數。 請依照通用的重試指引,按 HTTP 回應中
Retry-After指定的時間等候,並設定嘗試次數上限或截止時間。 - 重試請求或開始新的回合。 如果發生 HTTP 錯誤,請先確認原操作的結果,再重試該操作。如果回合失敗,請等到工作階段進入
idle狀態,再傳送後續訊息,要求智慧體只繼續執行未完成的工作。這會在現有對話中開始新的回合。
即使回合已完成,也請檢查工具結果。如果錯誤改變或已達重試次數上限,請停止自動重試。
修正無效輸入
請修正 error.param 或 error.message 指出的欄位,再重新提交。
如果錯誤與大小有關,請先縮減輸入和輸出結構描述或工具結果的大小,再重試。如果智慧體設定過大,請精簡指令和工具定義,再用來建立新的工作階段。
如需上傳要求和範例,請參閱排解上傳錯誤。如果錯誤訊息指出圖片有問題,請檢查圖片資料或 URL。
串流中斷
收到 error 事件或串流中斷時,仍無法確定回合的最終狀態。請依照恢復中斷的串流的步驟重新連線,並在重新提交輸入前檢查已儲存的工作。如果取得的工作階段顯示 status: "failed",或收到 agent.session.failed 事件,請停止嘗試重新連線,並依照工作階段復原指引處理。
如果錯誤持續發生,請在向支援團隊求助時附上請求 ID、工作階段 ID 和回合 ID。