指南OneMux

用可重複且有上限的測試計畫診斷 OpenAI API 故障

實用方法,協助區分 OpenAI API 的驗證、速率限制、逾時與回應格式錯誤,並在不無限重試或增加支出的情況下重新測試。

AI

摘要 · TL;DR

每次執行可重複的 OpenAI API 檢查時,都應記錄狀態、錯誤代碼、耗時與回應結構。只有暫時性故障才進行有限次重試;驗證、配額和請求錯誤應直接修正,而不是重試。

重點

  • 根據 HTTP 狀態與具體錯誤代碼判斷故障,不要只看狀態碼。
  • 對暫時性的速率限制與伺服器錯誤,在固定的重試次數與時間上限內重試;不要把驗證失敗或額度用盡當成暫時問題來重試。
  • 除了確認 HTTP 狀態成功,也要另外檢查回應結構。
  • 維持一組精簡且可重複執行的案例,並記錄重現各項故障所需的條件。
文章目錄 (6)

從有限範圍的診斷開始

OpenAI API 呼叫失敗時,先判斷問題出在存取權限、請求量、耗時,還是回傳資料。釐清原因後,才能決定要更換憑證、降低流量、重試,或驗證應用程式的剖析邏輯。單看 429 不足以判斷該如何修正:它可能代表暫時性的速率限制,也可能是支出或額度限制,而後者不會因再試一次就解除。

OpenAI 的錯誤代碼指南說明了 API 錯誤代碼,以及相應的 Python 程式庫例外類型。判讀觀察到的回應時,請以此為參考:OpenAI API 錯誤代碼。

分流處理四種常見故障

徵兆優先檢查下一步行動
401 驗證錯誤金鑰是否有效且啟用?使用的是否為預期的組織?修正金鑰或組織設定。若適用,也請檢查專案權限與 IP 允許清單。
429 回應查看具體錯誤代碼,以及是否有 Retry-After 標頭。若是速率限制,請調整請求頻率。若是額度用盡或支出或用量限制,應先解除限制再重試。
逾時或連線錯誤區分請求逾時與連線失敗。記錄耗時和網路狀況。若情況適合,可稍候片刻後謹慎重試;若是連線錯誤,請檢查 Proxy、憑證或防火牆規則。
HTTP 回應成功,但結果無法使用檢查本文能否解析,以及應用程式所需欄位是否存在且型別符合預期。將缺少或無效的欄位視為應用程式層級的回應驗證失敗,不要逕自判定為 API 驗證或速率限制錯誤。

OpenAI 指南指出,無效憑證會回傳 401;而 429 則有多種不同原因,包括請求速率、額度用盡,以及組織或專案限制。若是速率限制,指南建議在有提供 Retry-After 時遵循其指示。帳單、支出和配額錯誤都需要處理相應限制;反覆重試並不會恢復存取權限。指南也將 APITimeoutError 和 APIConnectionError 列為不同的 Python 程式庫例外。來源:OpenAI 錯誤代碼。

建立可重複執行的小型評估

請使用固定的一組案例,不要反覆傳送臨時編寫的提示。先從一次只隔離一項條件的案例開始:

  1. **基準測試:**傳送簡單且已知有效的輸入,確認預期的回應欄位存在。
  2. **驗證檢查:**使用預期的專案憑證執行相同的基準測試。不要在記錄或測試報告中刻意暴露真實金鑰。
  3. **請求驗證:**若測試環境允許,可在受控測試中省略或拼錯必要參數。記錄回傳的狀態和訊息;不要假設所有格式錯誤的請求都會以相同方式失敗。
  4. **速率限制處理:**使用模擬的 429 回應測試重試邏輯,並包含 Retry-After 標頭。避免產生真實流量來觸發限制。
  5. **逾時處理:**在用戶端或測試工具中模擬逾時。使用緩慢的測試端點或反覆呼叫正式環境,可能造成不必要的負載,也會讓結果難以判讀。
  6. **回應驗證:**測試有效的 JSON 本文中缺少必要欄位、欄位型別錯誤,以及無效 JSON 等情況。這些分別屬於不同的剖析或契約失敗。

每個案例都應記錄時間戳記與時區、端點或操作、模型、可取得的 HTTP 狀態、錯誤類型與代碼、嘗試次數、耗時,以及經過遮蔽的請求識別碼或診斷資訊。共用記錄中絕不可儲存憑證或敏感輸入。若要就持續發生的問題聯絡 OpenAI 支援,指南建議提供模型、錯誤與代碼、請求資料和標頭、時間戳記與時區,以及其他相關資訊;請先遮蔽機密和敏感資料。

為重試設定明確上限

只有在故障可能自行解除時,重試才有用。請設定應用程式回報失敗前的最大嘗試次數和總耗時。若收到速率限制回應,請遵循其提供的 Retry-After,並將重試次數限制在有限範圍內。針對伺服器錯誤,指南建議稍候片刻後重試;若問題持續,請查看狀態頁面或升級處理。401、格式錯誤的請求或額度用盡,都不是自動重試迴圈的理由。

在 Python 中,官方程式庫會區分 AuthenticationError、BadRequestError、RateLimitError、APITimeoutError 和 InternalServerError 等例外。請處理已安裝程式庫版本提供的例外類別,並在可取得時記錄狀態與錯誤代碼。以下範例僅供說明,用來展示分類方式,並非經測試的設定或適用所有情況的重試政策:

from openai import OpenAI

client = OpenAI()  # Supply credentials using your approved secret-management method.

try:
    response = client.responses.create(
        model="YOUR_SUPPORTED_MODEL",
        input="Return the word ready."
    )
    text = response.output_text
    if not isinstance(text, str) or not text.strip():
        raise ValueError("Response text is missing or empty")
    print(text)
except Exception as exc:
    # In production, classify known SDK exceptions explicitly and log
    # status/code when available. Do not log credentials or sensitive input.
    print(type(exc).__name__, str(exc))

請將模型佔位字串替換為專案可使用的模型。此範例並未證明特定模型、參數或供應商端點在您的環境中受到支援。若使用其他相容供應商,請先確認其端點和參數支援符合用戶端設定,再假設其行為完全相同。

區分格式錯誤的回應與 API 錯誤

HTTP 狀態成功,不代表應用程式一定收到預期內容。請在邊界處驗證回應:確認剖析成功、必要欄位存在,且值的型別可供使用。記錄精簡的驗證失敗說明,例如「缺少 output_text」或「預期為字串」,不要傾倒敏感的回應內容。

如果 API 回傳結構化錯誤,請在診斷資訊中保留其狀態和代碼。如果請求成功,但自己的剖析器拒絕本文,請將兩者分開標示。如此一來,便能清楚判斷應調查 API 存取或速率限制、請求建構、傳輸,還是應用程式本身的假設。

結論

實用的 OpenAI API 評估應精簡、可重現且有明確上限:包含一個基準測試、針對性的故障案例、明確的輸出檢查,以及固定的重試上限。記錄足夠的資訊以重現每項故障,並根據具體錯誤代碼,而非只看 HTTP 狀態,決定下一步行動。

常見問題

每次遇到 OpenAI 429 錯誤都應該重試嗎?

不應如此。請先檢查具體錯誤代碼。暫時性的請求速率限制可能需要調整請求頻率並遵循 `Retry-After`;若是額度用盡或支出及用量限制,則必須先解除限制再重試。

如何分辨 API 故障與格式錯誤的回應?

將 HTTP 狀態和 API 錯誤代碼,與應用程式驗證結果分開記錄。若回應成功,但無法解析或缺少必要欄位,這是回應驗證問題,不一定是 API 錯誤。

持續發生故障時,應收集哪些資訊?

記錄模型、錯誤訊息與代碼、請求情境與相關標頭、含時區的時間戳記、嘗試次數及耗時。分享記錄或支援資訊前,請先遮蔽 API 金鑰和敏感資料。

如何在不影響正式環境的情況下測試速率限制?

使用模擬的 429 回應測試重試行為,並加入模擬的 `Retry-After` 標頭。不要為了觸發速率限制而刻意對正式環境中的專案大量發送請求。

相關文章