當你的組織發送的請求數量或每分鐘代幣數量超過其限制時，OpenAI API 會回傳 429「Rate limit reached」。 限制適用於你的組織，而非針對每個使用者。 這些錯誤都是暫時性的。 如果你等著再再發送請求，通常會成功。 OpenAI 還有些 429 錯誤是關於帳單的，等著也不會消失。 欲了解更多資訊，請參閱 錯誤代碼。
OpenAI 的速率限制錯誤長什麼樣
| Status | 錯誤 | 這是什麼意思? | 重試？ |
|---|---|---|---|
429 |
rate_limit_exceeded，每分鐘請求次數（RPM） |
你一分鐘內寄了太多請求。 | 是的，在 Retry-After 之後 |
429 |
rate_limit_exceeded，每分鐘代幣數（TPM） |
你的請求一分鐘內用了太多代幣。 訊息會顯示你的上限、使用了多少代幣，以及該請求要求了多少代幣。 | 是的，在 Retry-After之後。 小請求會有幫助。 |
429 |
slow_down （類型 rate_limit_error） |
你的流量增長太快，儘管你都在轉速和TPM的限制內。 | 是的，但利率較低 |
503 |
server_is_overloaded （類型 service_unavailable_error） |
OpenAI 的伺服器很忙。 | 是的，每次延遲都比較長 |
429 |
credit_balance_exhausted、支出上限或使用上限錯誤（類型 insufficient_quota） |
你的點數用完了或超過了額度。 | No. 請參考 OpenAI insufficient_quota 和 credit_balance_exhausted。 |
大多數這些錯誤都具有相同的 429 狀態，所以你無法僅憑狀態分辨它們。 請閱讀 error.code 回應正文。
如何處理 OpenAI 速率限制錯誤
- 先檢查
error.code一下。 如果是像credit_balance_exhausted這樣的帳務代碼，請停止重試並告知使用者。 重新嘗試處理帳單錯誤也無法恢復存取權限。 - 當它出現時就依照
Retry-After。 如果缺少，使用帶有抖動的指數退縮，並限制重試次數。 - 在
slow_down之後放慢速度。 先降低請求速率，然後逐步增加。 OpenAI 的經驗法則是：當輸入 TPM 超過 100 萬時，每 15 分鐘增加的流量不應超過 50%。 - 發生 TPM 錯誤後，請傳送較少的權杖。 較短的提示詞和回應可讓每分鐘容納更多請求。
- 在
503之後再退後一些。 增加重試間隔，並查看 OpenAI 狀態頁面。 - 告訴使用者發生了什麼事。 「系統忙碌中，5 秒後重試」勝過一個永遠轉個不停的轉圈圈。
OpenAI Python SDK 預設會重試連線錯誤和 408、409、429 和 5xx 回應兩次，並採用短暫的指數退避。 你可以使用 max_retries 更改它。 當重試次數用盡時，SDK 會針對 429 引發 RateLimitError，並針對 503 引發 InternalServerError，因此你的程式碼仍需有所因應：
import openai
from openai import OpenAI
client = OpenAI(max_retries=3)
BILLING_CODES = {
"credit_balance_exhausted",
"organization_spend_limit_exceeded",
"project_spend_limit_exceeded",
"organization_usage_limit_exceeded",
}
def summarize(text: str) -> str | None:
try:
response = client.responses.create(model="gpt-4.1", input=text)
return response.output_text
except openai.RateLimitError as error:
if error.code in BILLING_CODES:
raise # Retrying won't help: alert and tell the user
return None # Still throttled after retries: show "busy, try again"
except openai.InternalServerError:
return None
如何測試你的應用程式是否能處理 OpenAI 速率限制
開發過程中很少會達到 OpenAI 的速率上限。 你是唯一的使用者，提示也很短。 所以你測試速率限制處理的方式，決定了你是否比使用者先發現錯誤。
| Approach | 你發現的 | 你錯過了什麼 |
|---|---|---|
| 等待正式環境 | 實際失敗 | 在使用者點擊它之前的一切 |
| 在測試中模擬 API，或讓你的程式設計代理寫出模擬 | 不管你的重試分支是否執行 | OpenAI 的真實錯誤主體和程式碼，以及你 SDK 的重試政策。 你的應用程式也需要一個只供測試使用的開關來連到模擬服務。 |
| 呼叫實際 API，直到它對你進行限流 | 實際行為 | 你無法按需觸發特定錯誤，且每個請求都需要代幣 |
| 攔截應用程式的實際流量，並依需求回傳 OpenAI 錯誤 | 真實網址、真實的 SDK 與重試政策，以及 OpenAI 自有的錯誤格式 | 你的應用程式裡沒有任何變化，因此無法以隔離方式測試你的程式碼。 那個就留給單元測試吧。 |
在你的應用程式上試試看
Dev Proxy 會攔截你應用程式對 api.openai.com 的請求並回傳 OpenAI 錯誤，而你的應用程式則持續呼叫真實的 URL。
openai-throttling 預設在大多數請求中都會失敗，並以 OpenAI 自身的格式隨機出現 TPM 和 RPM rate_limit_exceeded、slow_down、credit_balance_exhausted 與 503server_is_overloaded 錯誤。
429 速率限制回應包含 Retry-After 標頭，如果你的應用程式在該時間到期前重試，Dev Proxy 會回報。
下載預設集，並用它啟動 Dev Proxy：
devproxy config get openai-throttling
devproxy --config-file "~dataFolder/configs/openai-throttling/.devproxy/devproxyrc.json"
然後照常執行你的應用程式，觀察它的表現。 要安裝 Dev Proxy，請參見 設定 Dev Proxy。
要測試應用程式在每分鐘代幣用盡時的行為，根據請求使用的提示詞和完成代幣，請參考 測試語言模型代幣限制。
