速率限制是指 API 對使用者或用戶端在指定時間內可存取服務的次數所設的上限。
為什麼要設定速率限制?
設定速率限制是 API 的常見做法,原因如下:
- 速率限制有助於防止 API 遭到濫用或誤用。 例如,惡意人士可能向 API 發送大量請求,企圖使其過載或干擾服務。OpenAI 可透過速率限制防止這類行為。
- 速率限制有助於確保每個人都能公平使用 API。 如果某個人或組織發送過多請求,其他人使用 API 時也可能遇到延遲。OpenAI 藉由限制單一使用者可發送的請求數,讓盡可能多的人能順暢使用 API。
- 速率限制有助於 OpenAI 管理基礎設施的整體負載。 API 請求量激增可能讓伺服器不堪負荷,影響效能。設定速率限制有助於 OpenAI 為所有使用者維持順暢、穩定的使用體驗。
請閱讀完整文件,以瞭解 OpenAI 的速率限制機制。本文提供程式碼範例與常見問題的可能解法。下方的使用層級一節也會說明速率上限如何自動調高。
速率限制如何運作?
速率限制採用的指標包括 RPM(每分鐘請求數)、RPD(每日請求數)、TPM(每分鐘 Token 數)、TPD(每日 Token 數)和 IPM(每分鐘圖片數)。部分串流音訊模型也會計算每分鐘可處理的音訊分鐘數。任一指標先達上限,就會觸及速率限制。例如,假設你的 RPM 上限為 20,TPM 上限為 150,000。即使你在一分鐘內向 ChatCompletions 端點發送的 20 個請求總共只有 100 個 Token,遠低於 150,000 個 Token,請求數仍已達到上限。
Batch API 的佇列上限按各模型佇列中的輸入 Token 總數計算。尚未完成的批次作業所含的 Token 都會計入佇列用量。批次作業一旦完成,其 Token 就不再占用該模型的佇列額度。
另請留意以下事項:
- 速率限制適用於組織層級與專案層級,不會按個別使用者計算。
- 速率限制因所使用的模型而異。
- GPT-5.5 等支援長上下文的模型會對長上下文請求另設速率限制。你可以在開發人員主控台查看這些限制。
- OpenAI 會為每個組織核定每月使用上限。此上限與你可以為組織或專案設定的支出上限分開計算。
- 部分模型系列共用速率限制。組織限制頁面上列在同一個「共用上限」下的模型共用一個速率上限。例如,如果共用 TPM 上限為 350 萬,呼叫該「共用上限」清單中的任何模型,都會計入這 350 萬個 Token 的額度。
- 將資料匯入向量儲存庫時,也會按向量儲存庫 ID 套用速率限制。每個向量儲存庫的
/vector_stores/{vector_store_id}/files和/vector_stores/{vector_store_id}/file_batches共用每分鐘 300 個請求的上限。匯入大量資料時,建議使用/vector_stores/{vector_store_id}/file_batches。
使用層級
三個付費使用層級分別為 Build、Launch 和 Grow。組織購買點數的累計金額每達到一個門檻,使用層級就會自動升級。層級越高,各模型的速率上限通常也越高。
使用層級說明各層級適用的速率限制。即使某個模型列在速率限制清單中,也不代表你的組織、專案或 API 金鑰有權存取該模型。如果找不到某個模型,請檢查模型可用性。
| 層級 | 資格條件 | 使用上限 |
|---|---|---|
| 免費 | 使用者必須位於支援的地區 | 每月 $100 |
| Build | 累計購買 $5 的點數 | 每月 $500 |
| Launch | 累計購買 $100 的點數 | 每月 $5,000 |
| Grow | 累計購買 $500 的點數 | 每月 $200,000 |
標準速率限制
若要查看目前使用層級中各模型的上限,請前往設定 > 組織 > 限制,查看速率限制。若要升級使用層級,請選取升級層級,此選項位於使用層級區段。
這些標準速率限制與超高速模式的速率限制不同。
| 層級 | 模型 | RPM | TPM |
|---|---|---|---|
| Build | Astra、Sol、Terra | 5,000 | 1,000,000 |
| Luna | 5,000 | 2,000,000 | |
| Launch | Astra、Sol、Terra | 10,000 | 4,000,000 |
| Luna | 10,000 | 10,000,000 | |
| Grow | Astra、Sol、Terra | 15,000 | 40,000,000 |
| Luna | 30,000 | 180,000,000 |
支出上限
你可以為組織或專案設定支出上限,以控管每月 API 支出。這些設定與上述每月使用上限各自獨立。
回應標頭中的速率限制資訊
除了在帳戶頁面查看速率限制,你也可以從 HTTP 回應標頭取得重要資訊,包括剩餘的請求數、Token 數及其他中繼資料。
回應可能包含下列標頭欄位:
| 欄位 | 範例值 | 說明 |
|---|---|---|
| Retry-After | 56 | 若有此欄位,其值表示遇到暫時性速率限制錯誤後,重試前至少須等待的秒數。 |
| x-ratelimit-limit-requests | 60 | 速率限制允許的請求總數上限。 |
| x-ratelimit-limit-tokens | 150000 | 速率限制允許的 Token 總數上限。 |
| x-ratelimit-remaining-requests | 59 | 達到速率上限前還可發送的請求數。 |
| x-ratelimit-remaining-tokens | 149984 | 達到速率上限前還可使用的 Token 數。 |
| x-ratelimit-reset-requests | 1s | 距離請求數額度重設為初始值的時間。 |
| x-ratelimit-reset-tokens | 6m0s | 距離 Token 額度重設為初始值的時間。 |
| x-ratelimit-limit-project-tokens | 60000 | 專案的 Token 上限。 |
| x-ratelimit-remaining-project-tokens | 57000 | 達到專案的 Token 速率上限前還可使用的 Token 數。 |
| x-ratelimit-reset-project-tokens | 3s | 距離專案的 Token 額度重設為初始值的時間。 |
如果請求受專案層級的 Token 上限約束,回應可能會包含專案 Token 標頭。Retry-After 可能出現在暫時性速率限制引起的 429 回應,或模型暫時過載引起的 503 回應中。這個標頭並不表示重試就能解決配額、帳務或其他需要使用者處理的錯誤。
微調速率限制
你可以在控制台查看組織的微調速率限制,也可以透過 API 取得這些資訊:
curl https://api.openai.com/v1/fine_tuning/model_limits \
-H "Authorization: Bearer $OPENAI_API_KEY"模型可用性
模型存取權與速率限制各自獨立。達到使用層級的門檻,並不代表你就能存取所有模型。如果文件列出的模型未出現在 Playground 或 GET /v1/models 的回應中,或是請求傳回 model_not_found,請依序檢查:
- 檢查模型 ID 和端點。 請使用與模型文件完全相同的模型 ID,確認該模型支援你使用的端點,並查看是否有關於模型停用或可用性的公告。
- 核對組織、專案和憑證。 在 Playground 中選取你要使用的組織和專案。呼叫列出模型時,請使用與失敗請求相同的 API 金鑰。如果該請求包含
OpenAI-Organization或OpenAI-Project標頭,也請帶入相同的標頭和值。即使你登入控制台後看得到某個模型,使用其他 API 金鑰時仍可能無法存取該模型。 - 檢查專案限制與模型要求。 請有權管理該專案的人員檢查專案的模型權限與資料保留設定。請依照該模型的存取要求辦理,並查看模型文件中是否有分階段開放的公告。僅憑模型未出現在清單中,無法判斷原因。
- 重新整理後再檢查一次。 變更存取設定後,請重新整理模型清單或 Playground。如果仍無法使用該模型,請聯絡支援團隊,並提供模型 ID、組織 ID、專案 ID、發送請求的時間和錯誤訊息。如果回應包含
x-request-id標頭,也請提供其值。請勿分享你的 API 金鑰。
減輕錯誤的影響
處理流量激增與模型過載
當請求速率上升過快時,API 可能會傳回 slow_down。當請求使用的模型暫時過載時,API 可能會傳回 server_is_overloaded。請檢查 HTTP 狀態碼和 error.code 以區分這兩種情況:
| HTTP 狀態碼 | 錯誤類型 | 錯誤碼 | 含義 | 處理方式 |
|---|---|---|---|---|
429 |
rate_limit_error |
slow_down |
請求速率上升過快。 | 若有 Retry-After,請依其指定的時間等待,降低請求速率,再逐步調高。 |
503 |
service_unavailable_error |
server_is_overloaded |
請求使用的模型暫時過載。 | 若有 Retry-After,請依其指定的時間等待後再重試。如果錯誤持續發生,請拉長重試間隔。 |
如果沒有 Retry-After,請拉長重試間隔,並額外加入一小段隨機延遲。
即使流量未超過每分鐘請求數和每分鐘 Token 數的上限,仍可能出現 slow_down 錯誤。這個錯誤反映的是流量增加的速度,與是否用盡這些額度無關。
一般而言,流量一旦達到每分鐘 100 萬個輸入 Token(TPM),之後每 15 分鐘的增幅就應控制在 50% 以內。實際開始限制流量增速的門檻可能因模型和流量狀況而異。
若企業客戶的隨用隨付流量經常觸及流量增速上限,可以考慮使用規模層級,讓適用模型的可用容量更容易預估。如使用 GPT-5.6 或後續模型,請參閱預留層級。不論採用哪種容量層級,處理 slow_down 回應的方式都相同:若有 Retry-After,請依其指定的時間等待,降低流量,再逐步增加。
更新現有的錯誤處理程式
如果你的應用程式已有處理舊版限流與過載回應的邏輯,請同時檢查 HTTP 狀態碼和 error.code:
- 部分端點過去在這兩種情況下都會傳回
503和錯誤碼slow_down。現在,流量上升過快時會傳回429和slow_down。模型過載時仍會傳回503,但錯誤碼改為server_is_overloaded。 - 過去,影片請求若因上述情況而在建立作業前遭拒,會傳回
429,錯誤類型為invalid_request_error,錯誤碼為rate_limit_exceeded。現在,流量上升過快時會傳回429、rate_limit_error和slow_down。模型過載時則會傳回503、service_unavailable_error和server_is_overloaded。影片作業狀態中回報的錯誤屬於另一種情況。
請在 SDK 錯誤處理程式中同時處理 429 和 503。例如,Python、TypeScript 和 Ruby 以 RateLimitError 表示 429,以 InternalServerError 表示 503。Java 則分別使用 RateLimitException 和 InternalServerException。只要應用程式仍可能收到舊版回應碼,就應保留相應的處理邏輯。其他錯誤也可能使用相同的 HTTP 狀態碼,因此請先檢查錯誤回應本文,再決定如何復原。
對於串流請求,這些 HTTP 錯誤回應適用於串流開始前。串流開始後,錯誤可能會以串流事件的形式送達。如果已讀取輸出,請勿自動重新發送請求。
可以採取哪些措施減輕影響?
OpenAI Cookbook 提供 Python 筆記本,說明如何避免速率限制錯誤,也提供 Python 指令碼範例,示範如何批次處理 API 請求而不超過速率上限。
提供程式化存取、大量處理或自動在社群媒體發文的功能時,也請謹慎評估。建議只對可信任的客戶開放這些功能。
為防範自動化和大規模濫用,請為個別使用者設定指定期間內的使用上限,例如每日、每週或每月上限。對於超過上限的使用者,可考慮強制限制用量或啟動人工審查流程。
以指數退避方式重試
當請求超過暫時性速率上限時,API 會傳回 429 錯誤。回應可能包含 Retry-After 標頭,指出重試前要等待的秒數。請至少等待指定的時間,再額外加入一小段隨機延遲,以免多個用戶端同時重試。
每個 OpenAI 官方 SDK 都會依據重試設定,自動重試符合條件的 429 和 503 回應。各 SDK 版本與設定處理 Retry-After 的方式可能不同,尤其是等待時間較長時。請確認已安裝版本的重試行為,不要假設它支援伺服器指定的所有等待時間。
如果伺服器指定的等待時間有效,但超過支援或設定的重試等待上限,請停止重試並延後處理該請求,切勿提早重試。SDK 若不接受超過上限的等待時間,可能會傳回原始 HTTP 錯誤。請繼續分別處理取消和逾時錯誤:請求遭取消或已過截止時間,都可能使重試停止,而不傳回該 HTTP 錯誤。單次嘗試的逾時設定不一定會限制整個操作的總時間。
如果使用自己的 HTTP 用戶端,當回應包含 Retry-After 標頭且其值有效時,請依其指定的時間等待。如果標頭缺漏或值無效,請改用帶有隨機抖動的指數退避。同時限制嘗試次數與重試總時間。如果由應用程式管理重試,請停用 SDK 的重試功能,或將 SDK 的重試也計入上述限制,以免巢狀重試迴圈讓請求數倍增。遇到配額、帳務或其他需要你採取行動才能解決的錯誤時,請勿重試。
指數退避是指在請求失敗後先短暫等待,再於每次重試失敗後按指數增加等待時間,直到請求成功或達到設定的重試上限。
這種做法有幾項好處:
- 自動重試可讓應用程式從速率限制錯誤中復原,避免當機或遺漏資料。
- 指數退避可讓前幾次重試迅速進行。如果這些嘗試失敗,後續重試仍可拉長等待時間。
- 在等待時間中加入隨機抖動,有助於錯開各個請求的重試時間。
請注意,失敗的請求也會計入每分鐘用量,因此不斷重新發送請求無法解決問題。
下列範例示範如何重試使用 gpt-6-luna 的 Responses API 請求。每個包裝函式都會限制嘗試次數,並停用 SDK 內建的重試功能。
下方的 Python 範例示範如何在無法取得有效等待時間時使用退避機制。這些範例不會檢查 Retry-After。使用前,請先加入處理伺服器有效等待時間的邏輯,避免包裝函式提早重試。請停用 SDK 的重試功能,或將 SDK 的重試計入應用程式的重試上限。
調低 max_tokens 以符合預期的回應長度
計算速率限制用量時,系統會比較 max_tokens 與根據請求字元數估算的 Token 數,並採用兩者中較大的值。請盡量將 max_tokens 設為接近預期回應長度的值。
批次處理請求
如果你的使用情境不需要立即取得回應,可以使用 Batch API 提交並執行大批請求,不會占用同步請求的速率額度。
如果你的使用情境 確實 需要同步回應,OpenAI API 會分別限制每分鐘請求數和每分鐘 Token 數。
如果每分鐘請求數已達上限,但每分鐘 Token 額度仍有餘裕,可以在每個請求中合併多項任務,以提高吞吐量。這樣每分鐘就能處理更多 Token,使用較小的模型時尤其有效。
批次發送提示詞的方式與一般 API 呼叫相同,差別只在於傳給 prompt 參數的是字串清單,而非單一字串。如需詳細說明,請參閱 Batch API 指南。