當你的帳戶用盡點數或超過消費或使用限制時，OpenAI API 會回傳 429 錯誤類型 insufficient_quota 。 它的狀態碼和速率限制一樣，但等幾秒鐘也解決不了。 只有在有人加點數、提高限制或每月期間重置後，才能恢復使用權。 OpenAI 表示，重新嘗試計費、支出或配額相關操作無法恢復 API 存取權，建議你檢查 error.code 以找出具體原因。 欲了解更多資訊，請參閱 錯誤代碼。
OpenAI 的配額錯誤長什麼樣子
這些錯誤中每個都會回傳 429。
error.type仍然可能是insufficient_quota，所以請確認error.code你拿到的是哪一種。
error.code |
這是什麼意思? | 存取權如何恢復 |
|---|---|---|
credit_balance_exhausted |
您的組織已經沒有預付餘額了。 | 新增點數。 |
organization_spend_limit_exceeded |
您的組織在所有專案中都達到了每月支出上限。 | 可以提高或取消限制，或等待每月重置。 |
project_spend_limit_exceeded |
該計畫達到每月支出上限。 其他專案則持續運作。 | 可以提高或移除專案的上限，或等待每月重置。 |
organization_usage_limit_exceeded |
貴組織已達到 OpenAI 指定給貴組織的每月使用上限。 這和你設定的支出上限是分開的。 | 申請提高核准額度，或聯絡 OpenAI 支援團隊。 |
將這些與「速率上限已達」錯誤（如 rate_limit_exceeded 和 slow_down）比較。 這些都是暫時的，等一會兒重試通常都行。 欲了解更多資訊，請參閱 OpenAI「速率上限已達」錯誤。
如何處理 OpenAI 配額錯誤
- 查看
error.code，不要只看狀態。 單靠429並無法判斷是否需要重試。 將表中的 4 個代碼視為「停止」，並將速率限制代碼視為「等待後重試」。 - 停止重試。 不要再傳送請求，也不要讓重試迴圈一直呼叫 API。 在有人修復帳單問題之前，每次請求都會以同樣方式失敗。
- 暫停那些會失敗的呼叫。 一旦配額錯誤，下一個來自同一組織或專案的請求也會失敗。 跳過它們，不要每張都寄出再等到出現錯誤。
- 告訴使用者。 說明 AI 功能目前無法使用，並保持應用程式其他功能正常運作。
- 為自己設定提醒 將此代碼記錄為高嚴重性，或通知帳務負責人。 修正不在你的程式碼裡，所以需要有人知道這件事。
OpenAI Python SDK 預設會將429回應重試 2 次。 不管它重試什麼，你的程式碼最終都會隨著帳單代碼取得 RateLimitError，而那就是你要停止的地方：
import logging
import openai
from openai import OpenAI
client = OpenAI()
logger = logging.getLogger(__name__)
BILLING_CODES = {
"credit_balance_exhausted",
"organization_spend_limit_exceeded",
"project_spend_limit_exceeded",
"organization_usage_limit_exceeded",
}
billing_error: str | None = None
def ask(prompt: str) -> str:
global billing_error
if billing_error:
raise RuntimeError("AI features are paused until billing is fixed.")
try:
response = client.responses.create(model="gpt-4.1", input=prompt)
return response.output_text
except openai.RateLimitError as error:
if error.code in BILLING_CODES:
billing_error = error.code
logger.critical("OpenAI billing error: %s", error.code)
raise
這個旗標會一直保持在你的應用程式重新啟動前保持不變。 如果你的應用程式運行時間很長，可以用另一種方式清除，例如有人修復帳單後用管理員操作。
如何測試你的應用程式是否能處理 OpenAI 配額錯誤
在開發時，你很少會看到配額錯誤。 你的測試帳號有點數，使用量也很低。 所以你測試配額處理的方式，決定了你是否比使用者先發現錯誤。
| Approach | 你發現的 | 你錯過了什麼 |
|---|---|---|
| 等待正式環境 | 實際失敗 | 一切正常，直到有使用者按下去，而 AI 功能就會一直停用，直到有人注意到為止 |
| 在測試中模擬 API，或讓你的編碼代理寫出模擬 | 不管你的停止分支是否運行 | OpenAI 的真實錯誤回應本文和代碼，以及你的 SDK 重試政策。 你的應用程式也需要一個僅供測試使用的開關來連到模擬環境。 |
| 用掉你的實際點數，或設定一點點花費上限 | 實際行為 | 它需要付費，且會阻止與其共用同一組織或專案的其他應用程式 |
| 攔截你應用程式的真實流量，並按需回傳配額錯誤 | 真實網址、真實的 SDK 與重試政策，以及 OpenAI 自有的錯誤格式 | 你的應用程式中的任何內容都不會改變，所以它不會在隔離狀態下測試你的程式碼。 那件事就留給單元測試吧。 |
在你的應用程式中試試看
Dev Proxy 會攔截你應用程式對 api.openai.com 的請求，並回傳 OpenAI 錯誤，而你的應用程式則持續呼叫真實的 URL。 預設 openai-throttling 會將 credit_balance_exhausted 錯誤混入速率限制錯誤中。 它會回傳 429 有型別 insufficient_quota 但沒有 Retry-After 標頭，所以你可以檢查應用程式是否停止，而不是重試。
下載預設集，並用它啟動 Dev Proxy：
devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"
只測試配額錯誤時，編輯預設集的 openai-errors.json 檔案並只保留 credit_balance_exhausted 回應。 要測試支出和使用限制碼，加入形狀相同但 code 不同的回應。
然後照常執行你的應用程式，觀察它的表現。 要安裝 Dev Proxy，請參見 設定 Dev Proxy。
