OpenAI API 報錯 400、401、403、404、429、500、503 怎麼排查：按官方錯誤碼頁逐個看原因和解決辦法

本文根據 OpenAI 官方《Error codes》和《Rate limits》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。本站（bigolab.com）不是 OpenAI 官方網站。API 是按用量計費的獨立服務，與 ChatGPT 訂閱分開計算，Key 的獲取見 /guides/openai-api-key。

適用於誰

• 調用 OpenAI API 時拿到一個狀態碼，不知道是代碼問題、帳號問題還是官方服務問題的開發者；
• 想在程序裏把不同錯誤分開處理的人；
• 想先對號入座，再決定要不要讀更長的排查文章的人。

結論先說

1. 先看狀態碼，再看 error.code。 同樣是 429，可能是請求太快，也可能是額度用完、觸發了花費上限，處理方法完全不同。
2. 4xx 多半要你自己改：參數、Key、組織、權限、額度。5xx 才是官方一側的問題。
3. 帳單、花費、配額類錯誤重試沒用，官方明確說要先更新額度或上限再發請求。
4. 官方錯誤碼頁沒有單獨寫 404。 404 對應的資訊只在 Python 庫錯誤類型 NotFoundError 裏，本文第四節如實說明。
5. 服務端錯誤（500、503）：稍等重試，並看官方狀態頁。

圖：本站根據 OpenAI 官方《Error codes》 整理的示意圖

一、400：請求本身有問題

官方錯誤表裏 400 有一條：Invalid service_tier argument。原因是你請求的（或自動解析出的）服務層級，該項目不允許使用。官方說明，錯誤裏 error.param 是 service_tier，類型是 invalid_request_error；項目限制針對 default、flex、priority 這幾個服務層級，fast 按 priority 計算；就算你沒寫 service_tier 或寫了 auto，只要解析出來的層級不被允許，也會報這個錯。解決辦法：

• 到項目設定和組織設定裏看允許的服務層級，項目不能開啟組織已禁用的層級；
• 把 service_tier 設成項目允許的層級；
• 如果你用的是 auto 或沒寫，就調整項目設定，讓解析出的層級被允許。

其他 400 大多對應 Python 庫裏的 BadRequestError：請求格式不對或缺必需參數。官方的排查步驟是：

• 仔細讀錯誤訊息，它會指出哪個參數無效或缺失、期望什麼值或格式；
• 對照 API 參考，核對參數名、類型、取值和格式；
• 檢查請求數據的編碼、格式和大小：UTF-8、JSON，數據太大時壓縮；
• 用 Postman 或 curl 單獨復現，排除自己代碼裏的問題。

二、401：認證失敗

官方列了四種 401：

1）Invalid Authentication。 憑據無效。可能是用了已撤銷的 Key；用了不屬於該組織或項目的 Key；Key 沒有調用該接口所需的權限。解決：檢查請求頭裏的 Key 和組織是否正確，不確定就重新生成一個並替換。

2）Incorrect API key provided。 Key 不對。可能是有拼寫錯誤或多了空格；用了別的組織或項目的 Key；Key 已被刪除或停用；本地緩存了舊的已撤銷的 Key。官方建議：清除瀏覽器緩存和 Cookie 後重試，檢查請求頭裏的 Key，必要時重新生成，並遵循官方的 Key 安全使用最佳實踐。Key 怎麼申請和保管見 /guides/openai-api-key。

3）You must be a member of an organization to use the API。 你的帳號不在任何組織裏。可能是離開或被移出了原組織/項目，或組織被刪除。解決：向官方申請新組織，或請組織所有者在團隊頁面邀請你，也可以讓項目所有者把你加進項目。

4）IP not authorized。 請求的 IP 與項目或組織配置的 IP 白名單不符。解決：從正確的 IP 發送，或更新 IP 白名單設定。這一條是別人給你的組織設了白名單才會遇到。

三、403：國家、地區不支持

官方表裏 403 只有一條：Country, region, or territory not supported，表示你訪問 API 的國家、地區不在官方支持範圍。官方的解決辦法就是看支持國家和地區的頁面。本站不提供也不建議任何繞過辦法，請以官方 Supported countries 頁面為準。

四、404：官方頁面裏的位置

官方《Error codes》的 API 錯誤表裏沒有單獨的 404 條目。404 相關的資訊只在同頁的 Python 庫錯誤類型裏：NotFoundError，官方的原因是“請求的資源不存在”，解決辦法是確認你使用了正確的資源標識符。

結合官方這句話，本站的排查思路（推斷，不是官方逐條說明）是：看看請求路徑裏和參數裏涉及的標識符，例如模型名、文件 ID、響應 ID、批次 ID 有沒有寫錯、是不是已被刪除，是不是用了別的項目裏的資源。如果是通過 SDK 調用，拋出的是 NotFoundError。

五、429：先看 error.code

429 在官方表裏有六條，最重要的是區分 error.code：

圖：本站根據 OpenAI 官方《Error codes》 整理的示意圖

• credit_balance_exhausted：組織的預付額度用完了。官方的辦法是到賬單設定裏添加額度；
• Rate limit reached for requests：請求太快。放慢節奏，有 Retry-After 就至少等那麼久；沒有就用帶隨機抖動的指數退避，並限制重試次數；
• slow_down（類型 rate_limit_error）：請求速度漲得太快，哪怕沒超過每分鐘請求數和 token 數也會觸發。降速後逐步提高；
• organization_spend_limit_exceeded：組織觸發了你設定的月度花費上限，調高或取消，否則等到月度上限重置；
• project_spend_limit_exceeded：同理，是項目級的花費上限，其他項目可以繼續用；
• organization_usage_limit_exceeded：觸發了 OpenAI 分配給組織的月度用量上限，這個與你自己設的花費上限是兩回事，可以申請更高的批准用量或聯絡支持。

官方特別說明：帳單相關錯誤請檢查 error.code，因為 error.type 仍可能是 insufficient_quota；重試帳單、花費或配額類錯誤不會恢復訪問。

"Rate limit reached for requests" 的常見原因，官方列了：循環或腳本發請求太頻繁；和別人共用 Key；免費帳號限額低；達到了項目設定的限額。限額按組織算而不是按用戶算，團隊裏別人的用量也會佔用。層級與限額見 /guides/openai-api-usage-tiers-rate-limits，具體排查見 /guides/openai-api-429-error。

六、500 和 503：官方一側

500：伺服器處理請求時出錯。 官方說原因在它們的伺服器。辦法：稍等片刻再重試，持續出現就聯絡官方，並查看官方狀態頁（status.openai.com）。Python 庫對應 InternalServerError，官方的步驟是先等幾秒重試，再看狀態頁有沒有進行中的事故或維護。

503：模型暫時過載。 類型 service_unavailable_error，code 是 server_is_overloaded，表示請求的模型暫時沒有足夠容量處理請求。有 Retry-After 就等那麼久再試，沒有就拉長重試間隔；持續出現就看狀態頁。

提醒：Python、TypeScript 等 SDK 裏，429 對應 RateLimitError，503 對應 InternalServerError，處理限速和過載時兩者都要處理，並檢查 error.code。

七、在代碼裏分開處理

官方的 Node 示例（儲存為 .mjs）：

javascript
import OpenAI from "openai";

const client = new OpenAI();

try {
  const response = await client.responses.create({
    model: "gpt-6-astra", // 以官方模型頁當天為準
    input: "Hello world",
  });
  console.log(response.output_text);
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("連不上 OpenAI API：", error.message);
  } else if (error instanceof OpenAI.RateLimitError) {
    console.error("請求超過限額：", error.message);
  } else if (error instanceof OpenAI.APIError) {
    console.error("API 返回錯誤：", error.status, error.message);
  } else {
    throw error;
  }
}

Python 版：

python
import openai
from openai import OpenAI

client = OpenAI()

try:
    response = client.responses.create(model="gpt-6-astra", input="Hello world")
except openai.APIConnectionError as e:
    print("連不上 OpenAI API：", e)
except openai.RateLimitError as e:
    print("請求超過限額：", e)
except openai.APIError as e:
    print("API 返回錯誤：", e)
else:
    print(response.output_text)

注意 APIError 要放在最後，因為前面兩個是它的子類。官方還說明 APIConnectionError 是網絡層面的問題，可能是網絡設定、代理配置、SSL 證書或防火牆規則；APITimeoutError 是請求耗時太長被伺服器斷開，等幾秒重試。

八、問題一直不好：聯絡官方時要帶什麼

官方在 Persistent errors 一節說，持續出錯時聯絡官方支持，並提供：使用的模型；錯誤訊息和 code；發送的請求數據和請求頭；請求的時間戳和時區；其他有助於診斷的細節。注意別把 Key 本身發給任何人。

常見問題

Q：同一個請求有時 200 有時 429？

先看是不是 slow_down，或者是批量並發。有關批處理的獨立限額，見 /guides/openai-api-batch。

Q：400 說模型不存在？

官方錯誤碼頁沒有單獨寫這種情況。按本文第四節的思路核對模型名，並以官方模型頁為準。

Q：帳單頁面看不到額度？

帳單和價格見 /guides/openai-api-pricing-billing，價格以官方價格頁當天為準。

參考資料

• OpenAI 官方：Error codes — https://developers.openai.com/api/docs/guides/error-codes
• OpenAI 官方：Rate limits — https://developers.openai.com/api/docs/guides/rate-limits