如何安全診斷 OpenAI API 驗證、速率限制、逾時與格式錯誤回應
實用且重視隱私的指南,說明如何診斷 OpenAI API 驗證、限流、逾時及格式錯誤回應問題,同時避免暴露憑證或使用者資料。
摘要 · 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 則可能表示所在地國家、區域或領土不受支援。
請依下列順序檢查:
- 確認伺服器讀取的是預期的密鑰,且該密鑰未遭截斷、過期、撤銷或替換。
- 確認請求傳送至預期的 API 端點和專案。
- 若設定使用組織識別碼或 IP 允許清單,請核對兩者與專案設定是否相符。
- 檢查請求是否來自不同的對外 IP,例如開發環境、容器或託管環境中的 IP。
- 分享記錄前,請先移除其中的所有憑證值。
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 用戶端或中介軟體,請分別進行以下檢查:
- 解析前先確認 HTTP 狀態和
Content-Type。 - 在受保護的程式區塊中解析 JSON。
- 使用資料前,先確認必要欄位存在。
- 僅記錄狀態、內容類型、回應長度,以及在政策允許時經遮蔽且有長度限制的摘要片段。
- 解析錯誤訊息中絕不可包含 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、截斷資料或改動回應。
相關文章
指南
保護客服分流流程中的 OpenAI API 金鑰
實用的客服分流安全流程:保護 API 金鑰、遮蔽記錄、限制權限、輪替憑證,並要求人工核准。
指南
診斷 OpenAI API 事故,同時避免憑證外洩
實用指南:如何在保護 API 金鑰、限制權限並規劃憑證輪替的同時,取得有效訊號以診斷 OpenAI API 故障。
指南
兼顧隱私的 GPT Image 2.6 API 工作負載成本估算
運用明確的 token 假設、驗收率及兼顧隱私的量測方式,估算 GPT Image 2.6 工作負載成本。
指南
GPT 6.2 Sol API 費用:兼顧隱私的工作負載估算
根據可比較的 token 價格、明確的工作負載假設,以及使用者資料與憑證的實務控管措施,估算 GPT 6.2 Sol API 費用。