指南OneMux

如何安全診斷 OpenAI API 驗證、速率限制、逾時與格式錯誤回應

實用且重視隱私的指南,說明如何診斷 OpenAI API 驗證、限流、逾時及格式錯誤回應問題,同時避免暴露憑證或使用者資料。

AI

摘要 · TL;DR

排查 OpenAI API 故障時,最安全的做法是在重試前先判斷故障類型。驗證錯誤通常需要修正金鑰、組織、專案或 IP 設定;速率與額度錯誤則需要調整呼叫頻率或進行管理設定;逾時可能只是暫時性問題;格式錯誤的回應則應視為傳輸、代理伺服器或解析問題,分開處理。記錄診斷中繼資料即可,不要記錄憑證或原始使用者內容。

重點

  • 401 驗證失敗,以及帳務或額度錯誤,不應當成暫時性網路錯誤反覆重試。
  • 遇到 429 限流和 503 過載回應時,若有 Retry-After,請遵循該值並採用有上限的指數退避。
  • API 金鑰不得放在原始碼、記錄、例外訊息或用戶端應用程式中。
  • 非 JSON 回應或 JSON 解析失敗,應視為獨立的傳輸或代理伺服器問題;診斷資訊應經過遮蔽並限制長度。
  • 若要回報持續發生的問題,請提供模型、錯誤代碼、時間戳記、時區及經清理的請求詳細資訊。
文章目錄 (7)

只要將 設定錯誤、容量問題、網路故障和回應解析失敗分開處理,OpenAI API 故障就更容易排查。首先應該問:重試有可能改變結果嗎?

401 通常不會因重試而改善。若 429 是因請求速度過快,降低呼叫頻率後可能會改善;若 429 是因點數用盡或支出上限,則需要調整帳戶或專案設定。逾時可能只是暫時性問題,但若反覆發生,可能代表網路、代理伺服器或請求大小有問題。

以下程序使用 JavaScript 和 OpenAI 官方程式庫的相關概念,並參考 OpenAI 錯誤代碼指南。這些程式碼僅示範處理模式,並非經過測試的正式環境整合方案。

開始除錯前:保護憑證與使用者資料

重現錯誤前,請先做好以下準備:

  • 將 API 金鑰存放在伺服器端的密鑰管理服務或環境變數中。切勿放入瀏覽器程式碼、行動應用程式、原始碼管理系統或支援工單。
  • 記錄請求時間戳記、端點類別、模型識別碼、HTTP 狀態,以及可取得的結構化錯誤代碼。
  • 不要記錄 Authorization 標頭、完整請求本文、原始回應本文,或含有個人資料的提示詞。
  • 若診斷時需要提示詞,請記錄遮蔽後的範例,或穩定的內部請求識別碼,而非原始文字。
  • 限制診斷資料的長度。代理伺服器可能會傳回大型 HTML 錯誤頁面,上游錯誤也可能包含您原本不打算保留的資料。

實用的作業原則是:讓記錄能回答出了什麼問題、發生在哪裡,但不要記錄使用者說了什麼或如何進行驗證。

優先診斷 401 驗證失敗

文件列出的 401 情況包括驗證無效、API 金鑰錯誤、缺少組織成員資格,以及未獲授權的 IP 位址。403 則可能表示所在地國家、區域或領土不受支援。

請依下列順序檢查:

  1. 確認伺服器讀取的是預期的密鑰,且該密鑰未遭截斷、過期、撤銷或替換。
  2. 確認請求傳送至預期的 API 端點和專案。
  3. 若設定使用組織識別碼或 IP 允許清單,請核對兩者與專案設定是否相符。
  4. 檢查請求是否來自不同的對外 IP,例如開發環境、容器或託管環境中的 IP。
  5. 分享記錄前,請先移除其中的所有憑證值。

401 或 403 不應自動重試。對同一個無效憑證重試只會增加雜訊,也可能讓事件分析更複雜。請先修正設定,再送出新請求。

區分 429 限流與額度、帳務問題

並非所有 429 都代表「稍後再試」。OpenAI 指南區分了以下幾種情況:

故障類別建議處理方式是否自動重試?
達到速率限制降低請求頻率,並在有 Retry-After 時遵循其值可以,但須設限
slow_down降低請求頻率,並逐步增加頻率可以,務必謹慎
點數餘額用盡購買點數否
組織或專案支出上限調整適用的上限否
組織使用量上限申請提高核准上限或聯絡支援否

重試迴圈應檢查 HTTP 狀態和具體錯誤代碼,不要把所有 429 都視為相同情況。請設定最大嘗試次數,採用指數退避和隨機抖動,避免多個工作程序同時重試。若有 Retry-After,應優先採用該延遲時間,但仍可依照您設定的最長等待時間加以限制。

也請一併考量 503 回應。來源文件指出,模型過載會以 server_is_overloaded 表示,並建議在有 Retry-After 時先遵循其值,再進行重試。在 Python 程式庫中,過載可能會以 InternalServerError 表示,而 429 回應則使用 RateLimitError;處理程式不應假設過載一定會以 429 傳回。

排查逾時與連線故障

OpenAI 官方 Python 程式庫以 APITimeoutError 表示請求逾時,以 APIConnectionError 表示連線問題。常見的診斷方向包括:

  • **收到回應前逾時:**檢查用戶端逾時設定、網路路由、代理伺服器、防火牆及請求大小。
  • **連線失敗:**檢查 DNS、TLS 憑證、對外防火牆規則及代理伺服器設定。
  • **伺服器端故障反覆發生:**查看服務狀態頁,並保留經清理的時間戳記,以便提供給支援人員。

逾時不代表伺服器一定沒有處理請求。若重複執行操作會造成問題,請設計應用程式,確保重試後能安全核對結果;例如,使用您自己的請求記錄來追蹤該操作。不要只靠無限制延長逾時時間或不設上限地重試來處理逾時。

處理格式錯誤回應,同時避免洩露內容

「格式錯誤的回應」可能指好幾種不同問題:無效請求導致 BadRequestError、回應不符合預期的結構描述,或代理伺服器傳回 HTML 或截斷資料,而非 JSON。OpenAI 指南將 BadRequestError 描述為格式錯誤或不完整的請求,並建議檢查必要參數、編碼、格式及大小。

若使用原始 HTTP 用戶端或中介軟體,請分別進行以下檢查:

  1. 解析前先確認 HTTP 狀態和 Content-Type。
  2. 在受保護的程式區塊中解析 JSON。
  3. 使用資料前,先確認必要欄位存在。
  4. 僅記錄狀態、內容類型、回應長度,以及在政策允許時經遮蔽且有長度限制的摘要片段。
  5. 解析錯誤訊息中絕不可包含 API 金鑰、完整提示詞或完整回應。

以下為一個示意包裝程式:

async function parseSafeResponse(response) {
  const contentType = response.headers.get("content-type") || "";
  const body = await response.text();

  if (!contentType.toLowerCase().includes("application/json")) {
    throw new Error(`Unexpected response type: ${contentType}; length=${body.length}`);
  }

  try {
    return JSON.parse(body);
  } catch {
    throw new Error(`Invalid JSON response; length=${body.length}`);
  }
}

這個範例刻意不在拋出的錯誤中包含本文。正式環境中,請依端點需求加入結構描述驗證,並且只在受控且經隱私審查的診斷流程中保留原始資料內容。

重視隱私的錯誤處理模式

OpenAI 官方 JavaScript 範例會區分連線錯誤、速率限制錯誤及更廣泛的 API 錯誤。您可以延伸這個做法,在不輸出機密或使用者輸入的情況下分類錯誤:

import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

try {
  const response = await client.responses.create({
    model: process.env.OPENAI_MODEL,
    input: "Redacted diagnostic input"
  });

  console.log({ ok: true, hasOutput: Boolean(response.output_text) });
} catch (error) {
  const details = {
    name: error?.name,
    status: error?.status,
    code: error?.code
  };

  if (error instanceof OpenAI.AuthenticationError) {
    console.error("Authentication failed", details);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("Rate limit or quota response", details);
  } else if (error instanceof OpenAI.APIConnectionError) {
    console.error("Connection failed", details);
  } else if (error instanceof OpenAI.APIError) {
    console.error("OpenAI API error", details);
  } else {
    console.error("Unexpected local error", { name: details.name });
  }
}

請依照您部署的 SDK 版本,確認類別名稱和端點行為。不要假設每個相容於供應商的端點都支援所有 SDK 參數或回應欄位。

何時升級處理

若故障持續發生,OpenAI 指南建議提供模型、錯誤訊息與代碼、請求資料與標頭、時間戳記、時區,以及其他相關資訊。請先清理這些資料:替換憑證、移除 Cookie、遮蔽個人資料,並盡可能以摘要取代請求本文。切勿在公開論壇張貼敏感資訊。

處理原則很簡單:修正驗證與額度問題;遇到限流或過載時採取退避;檢查逾時的網路邊界;並在不保留私人資料內容的情況下,獨立排查解析失敗。

常見問題

所有 OpenAI 429 回應都應該重試嗎?

不應如此。若回應表示請求頻率過高或需要減速,請謹慎重試並採用退避策略;若有 Retry-After,請遵循其值。點數用盡、支出上限或組織使用量上限,則無法靠重試解決。

為什麼 OpenAI 過載錯誤會以 503 而非 429 傳回?

OpenAI 錯誤指南指出,模型過載會以 503 和 server_is_overloaded 代碼表示。錯誤處理程式應同時檢查狀態和代碼,不要假設過載一定是速率限制回應。

OpenAI 驗證失敗時應記錄哪些資訊?

請記錄時間戳記、環境、端點類別、狀態及經清理的錯誤代碼。不要記錄 API 金鑰、Authorization 標頭、完整請求本文或原始使用者提示詞。

如何排查無效的 JSON 回應?

解析前先檢查 HTTP 狀態和 Content-Type;若政策允許,只擷取經遮蔽且有長度限制的診斷資訊;並檢查代理伺服器或中介軟體是否傳回 HTML、截斷資料或改動回應。

相關文章