本指南概述使用 API 與我們的官方 Python 函式庫 時可能遇到的錯誤代碼。概覽中列出的每個錯誤代碼都有專屬章節，提供進一步的指引。
程式碼 概覽 400 - 無效的 service_tier 引數 原因： 專案不允許請求指定或系統判定的服務層級。解決方法： 將 service_tier 設為專案允許的層級，或在專案設定 中更新允許的服務層級。401 - 身分驗證無效 原因： 身分驗證無效。解決方法： 確認使用的 API 金鑰 與發出請求的組織正確無誤。401 - 提供的 API 金鑰不正確 原因： 請求使用的 API 金鑰不正確。解決方法： 確認使用的 API 金鑰正確無誤、清除瀏覽器快取，或產生新的金鑰 。401 - 你必須是組織成員才能使用 API 原因： 你的帳戶不屬於任何組織。解決方法： 聯絡我們，讓我們將你加入新組織，或請組織管理員邀請你加入組織 。401 - IP 未獲授權 原因： 請求的來源 IP 不符合專案或組織設定的 IP 允許清單。解決方法： 從正確的 IP 傳送請求，或更新 IP 允許清單設定 。403 - 不支援的國家、地區或領土 原因： 你正從不支援的國家、地區或領土存取 API。解決方法： 請參閱此頁面 以瞭解詳情。429 - 點數餘額已用盡 程式碼： credit_balance_exhausted 原因： 組織的預付點數已用盡。解決方法： 加值點數 以繼續使用 API。429 - 已達請求速率限制 原因： 你傳送請求的速度過快。解決方法： 調整請求的傳送節奏，並在回應包含 Retry-After 標頭時遵循其指示。請閱讀速率限制指南 。429 - 請降低速度 類型： rate_limit_error 程式碼： slow_down 原因： 請求速率增加得太快。解決方法： 如果回應包含 Retry-After 標頭，請遵循其指示。請先降低請求速率，再逐步提高。429 - 已達組織支出上限 程式碼： organization_spend_limit_exceeded 原因： 組織已達到強制執行的支出上限。解決方法： 提高或移除組織支出上限 。429 - 已達專案支出上限 程式碼： project_spend_limit_exceeded 原因： 專案已達到強制執行的支出上限。解決方法： 在專案設定 中提高或移除支出上限。429 - 已達組織用量上限 程式碼： organization_usage_limit_exceeded 原因： 組織已達到 OpenAI 指定的用量上限。解決方法： 申請提高核准的用量上限 ，或聯絡支援團隊 。500 - 伺服器處理請求時發生錯誤 原因： 我們的伺服器發生問題。解決方法： 稍候片刻後重試請求；如果問題持續發生，請聯絡我們。請查看狀態頁面 。503 - 模型暫時過載 類型： service_unavailable_error 程式碼： server_is_overloaded 原因： 請求的模型暫時過載。解決方法： 如果回應包含 Retry-After 標頭，請遵循其指示，再重試請求。
遇到帳務相關錯誤時，請檢查 error.code 以找出具體原因。較廣泛的分類 error.type 仍可能是 insufficient_quota。
遇到帳務、支出或配額錯誤時，重試請求無法恢復 API 存取。請先更新相關點數或上限，再傳送另一個請求。
如果你使用 Responses API 的 WebSocket 模式 ，可能還會遇到以下錯誤：
previous_response_not_found：無法根據可用狀態解析 previous_response_id。請提供完整的輸入上下文，並將 previous_response_id 設為 null 後重試。websocket_connection_limit_reached：連線已達 60 分鐘的時限。請建立新的 WebSocket 連線以繼續。
400 - 無效的 service_tier 引數 當請求選擇或系統判定的服務層級不在專案允許的範圍內時，API 會傳回 invalid_request_error 錯誤，將 error.param 設為 service_tier，並附上訊息「Invalid service_tier argument: The requested service tier is not allowed for this project.」。
專案限制適用於 default、flex 和 priority 服務層級。fast 服務層級會視為 priority 進行評估。如果請求省略 service_tier 或將其設為 auto，而系統判定的層級不在允許範圍內，也可能傳回此錯誤。規模層級仍不受此專案政策限制。
若要解決此錯誤：
在專案設定 中檢查允許的服務層級。
將 service_tier 設為專案允許的層級。
如果請求使用 auto 或省略 service_tier，請更新專案設定，允許系統判定的層級。
401 - 身分驗證無效 此錯誤訊息表示你的身分驗證憑證無效。可能的原因包括：
你使用的 API 金鑰已遭撤銷。
你使用的 API 金鑰與指派給發出請求之組織或專案的金鑰不同。
你使用的 API 金鑰不具備呼叫該端點所需的權限。
若要解決此錯誤，請依照下列步驟操作：
確認請求標頭中的 API 金鑰與組織 ID 正確無誤。你可以在帳戶設定 中找到 API 金鑰與組織 ID，或在一般設定 中選擇所需的專案，以查找該專案的相關金鑰。
如果不確定 API 金鑰是否有效，你可以產生新的金鑰 。請務必將請求中的舊 API 金鑰替換為新金鑰，並遵循我們的最佳實務指南 。
401 - 提供的 API 金鑰不正確 此錯誤訊息表示你在請求中使用的 API 金鑰不正確。可能的原因包括：
API 金鑰中有輸入錯誤或多餘的空格。
你使用的 API 金鑰屬於其他組織或專案。
你使用的 API 金鑰已被刪除或停用。
本機可能快取了已遭撤銷的舊 API 金鑰。
若要解決此錯誤，請依照下列步驟操作：
請嘗試清除瀏覽器的快取與 Cookie，然後再試一次。
確認請求標頭中使用的是正確的 API 金鑰。
如果不確定 API 金鑰是否正確，可以產生新的金鑰 。請務必替換程式碼庫中的舊 API 金鑰，並遵循我們的最佳實務指南 。
401 - 你必須是組織成員才能使用 API 此錯誤訊息表示你的帳戶不屬於任何組織。可能的原因包括：
你已離開原本的組織，或已遭移除。
你已離開原本的專案，或已遭移除。
你的組織已遭刪除。
請依照下列步驟解決此錯誤：
如果你已離開原本的組織或已遭移除，可以申請新組織，或透過邀請加入現有組織。
若要申請新組織，請透過 help.openai.com 聯絡我們。
現有組織的擁有者可以透過團隊頁面 邀請你加入組織，也可以從設定頁面 建立新專案。
如果你已離開原本的專案或已遭移除，可以請組織或專案擁有者將你加入該專案，或建立新專案。
429 - 點數餘額已用盡 credit_balance_exhausted 錯誤表示你的組織已用盡預付點數餘額。
若要恢復 API 存取，請在帳務設定中加購點數 。
429 - 已達請求速率限制 此錯誤訊息表示你已達到獲配的 API 速率限制。這代表你在短時間內提交了過多 Token 或請求，超出了允許的請求數量。可能的原因包括：
你使用的迴圈或指令碼會頻繁或同時發出請求。
你與其他使用者或應用程式共用 API 金鑰。
你使用的免費方案速率限制較低。
你已達到專案設定的上限。
請依照下列步驟解決此錯誤：
控制請求的發送頻率，避免不必要或重複的呼叫。
如果回應包含 Retry-After 標頭，請至少等待該標頭指定的時間後再試一次。如果沒有此標頭，請使用加入隨機抖動的指數退避策略，並限制重試次數。SDK 對伺服器要求長時間等待的支援程度，會因版本和組態而異。詳情請參閱我們的速率限制指南 。
如果你與其他使用者同屬一個組織，請注意，限制是以組織為單位套用，而非個別使用者。建議檢查團隊其他成員的用量，因為這些用量也會計入上限。
如果你使用免費或較低層級的方案，可以考慮升級至速率限制較高的隨用隨付方案。你可以在我們的速率限制指南 中比較各方案的限制。
請聯絡組織擁有者，提高專案的速率限制。
429 - 請降低速率 如果 429 回應的類型為 rate_limit_error、代碼為 slow_down，表示請求速率增加得太快，超出了服務能安全處理的範圍。即使流量仍在每分鐘請求數和每分鐘 Token 數的限制內，也可能發生此錯誤。
一般建議，當流量達到每分鐘 100 萬個輸入 Token（TPM）後，每 15 分鐘的增幅不應超過 50%。流量增速限制的實際觸發門檻會因模型和流量狀況而異。
若要解決此錯誤：
如果回應包含 Retry-After 標頭，請至少等待該標頭指定的時間後再重試。如果沒有此標頭，請延長重試間隔，並加入短暫的隨機延遲。
先降低請求速率，再逐步提高。
保持流量穩定，以降低再次發生 slow_down 錯誤的機率。
如果企業客戶的隨用隨付流量經常觸及流量增速限制，可以考慮使用規模層級 ，為符合資格的模型取得更可預期的容量。若使用 GPT-5.6 及後續模型，請參閱預留層級 。這些容量選項無法取代上述恢復步驟：回應包含 Retry-After 時，仍須遵循其指示，並逐步增加流量。
429 - 已達組織支出上限 organization_spend_limit_exceeded 錯誤表示你的組織已達到強制執行的每月支出上限 。此上限適用於組織內所有專案的 API 流量。
若要恢復 API 存取，請在組織限制設定 中提高或移除此上限。否則，存取將在每月上限重設後恢復。
429 - 已達專案支出上限 project_spend_limit_exceeded 錯誤表示你的專案已達到強制執行的每月支出上限 。其他專案仍可繼續使用，除非也已達到各自的上限或組織上限。
若要恢復 API 存取，請在專案設定 中提高或移除此上限。否則，存取將在每月上限重設後恢復。
429 - 已達組織用量上限 organization_usage_limit_exceeded 錯誤表示你的組織已達到 OpenAI 指定的每月用量上限 。此上限與你自行設定的組織及專案支出上限互相獨立。
若要恢復 API 存取，請申請提高已核准的用量上限 ，或聯絡支援團隊 。
503 - 模型暫時過載 如果 503 回應的類型為 service_unavailable_error、代碼為 server_is_overloaded，表示所請求的模型目前沒有足夠容量處理你的請求。
如果回應包含 Retry-After 標頭，請至少等待該標頭指定的時間後再重試。如果沒有此標頭，請延長重試間隔。如果錯誤持續發生，請查看狀態頁面 ，確認是否有尚未解決的事件。
Python 會針對 429 回應引發 RateLimitError，並針對 503 回應引發 InternalServerError。如果你的處理常式先前僅捕捉其中一種例外類別來處理限流和過載，請改為處理這兩種類別，並檢查 error.code。例如，影片過載現在會回傳 503，先前則回傳 429。各端點的具體變更請參閱遷移指南 。
類型 概覽 APIConnectionError 原因： 連線至我們的服務時發生問題。 解決方法： 檢查網路設定、代理伺服器組態、SSL 憑證或防火牆規則。APITimeoutError 原因： 請求逾時。 解決方法： 稍候片刻再重試請求；如果問題持續發生，請聯絡我們。AuthenticationError 原因： 你的 API 金鑰或 Token 無效、已過期或已遭撤銷。 解決方法： 檢查 API 金鑰或 Token，確認其正確且有效。你可能需要從帳戶儀表板產生新的金鑰或 Token。BadRequestError 原因： 請求格式錯誤，或缺少某些必要參數，例如 Token 或輸入。 解決方法： 錯誤訊息應會指出具體問題。請查閱所呼叫 API 方法的文件 ，並確認傳送的參數有效且完整。你可能也需要檢查請求資料的編碼、格式或大小。ConflictError 原因： 資源已由另一個請求更新。 解決方法： 嘗試再次更新資源，並確認沒有其他請求正在嘗試更新同一資源。InternalServerError 原因： 我們這邊發生問題。 解決方法： 稍候片刻再重試請求；如果問題持續發生，請聯絡我們。NotFoundError 原因： 請求的資源不存在。解決方法： 請確認使用的資源識別碼正確。PermissionDeniedError 原因： 你沒有存取所請求資源的權限。解決方法： 請確認使用的 API 金鑰、組織 ID 和資源 ID 都正確。RateLimitError 原因： 你已達到獲配的速率限制，或流量增加得太快。解決方法： 請控制傳送請求的速度，並在回應包含 Retry-After 時遵循其指示，同時遵守你的重試限制。詳情請參閱我們的速率限制指南 。UnprocessableEntityError 原因： 請求格式正確，但仍無法處理。解決方法： 請重試該請求。
APIConnectionError APIConnectionError 表示你的請求無法送達我們的伺服器，或無法建立安全連線。這可能是網路問題、代理伺服器組態、SSL 憑證或防火牆規則所造成。
如果遇到 APIConnectionError，請嘗試以下步驟：
檢查網路設定，確認網際網路連線穩定且快速。你可能需要切換至其他網路、使用有線連線，或減少占用頻寬的裝置或應用程式數量。
檢查代理伺服器組態，確認它與我們的服務相容。你可能需要更新代理伺服器設定、改用其他代理伺服器，或完全不透過代理伺服器連線。
檢查 SSL 憑證，確認憑證有效且已更新。你可能需要安裝或更新憑證、改用其他憑證授權單位，或停用 SSL 驗證。
檢查防火牆規則，確認規則未封鎖或過濾我們的服務。你可能需要修改防火牆設定。
如果適用，請確認容器具備傳送和接收流量所需的權限。
如果問題持續發生，請參閱「持續發生的錯誤」一節，瞭解後續處理步驟。
APITimeoutError APITimeoutError 錯誤表示你的請求耗時過長，因此我們的伺服器關閉了連線。這可能是網路問題、我們的服務負載過重，或請求過於複雜而需要更多處理時間所造成。
如果遇到 APITimeoutError 錯誤，請嘗試以下步驟：
等待幾秒後再重試請求。有時網路壅塞情況或我們的服務負載可能會減輕，請求便可能在第二次嘗試時成功。
檢查網路設定，確認網際網路連線穩定且快速。你可能需要切換至其他網路、使用有線連線，或減少占用頻寬的裝置或應用程式數量。
如果問題持續發生，請參閱「持續發生的錯誤」一節，瞭解後續處理步驟。
AuthenticationError AuthenticationError 表示你的 API 金鑰或 Token 無效、已過期或已撤銷。這可能是輸入錯誤、格式錯誤或安全性遭入侵所造成。
如果遇到 AuthenticationError，請嘗試以下步驟：
檢查 API 金鑰或 Token，確認它正確且有效。你可能需要在 API 金鑰儀表板產生新的金鑰、確認沒有多餘的空格或字元，或在擁有多組金鑰或 Token 時改用另一組。
確認你使用了正確的格式。
BadRequestError BadRequestError（舊稱 InvalidRequestError）表示你的請求格式有誤，或缺少某些必要參數，例如 Token 或輸入內容。這可能是輸入錯誤、格式錯誤或程式碼中的邏輯錯誤所造成。
如果遇到 BadRequestError，請嘗試以下步驟：
仔細閱讀錯誤訊息，找出具體的錯誤。錯誤訊息應會指出哪個參數無效或缺漏，以及預期的值或格式。
查閱 API 參考文件 中你所呼叫的 API 方法，確認傳送的參數有效且完整。你可能需要檢查參數名稱、型別、值和格式，確保它們符合文件中的說明。
檢查請求資料的編碼、格式或大小，確認它們與我們的服務相容。你可能需要以 UTF-8 編碼資料、使用 JSON 格式，或在資料過大時進行壓縮。
使用 Postman 或 curl 等工具測試請求，確認它能如預期運作。你可能需要對程式碼進行偵錯，並修正請求邏輯中的錯誤或不一致之處。
如果問題持續發生，請參閱「持續發生的錯誤」一節，瞭解後續處理步驟。
InternalServerError InternalServerError 表示我們在處理你的請求時發生了問題。這可能是暫時性錯誤、程式錯誤或系統中斷所造成。
對於造成的不便，我們深感抱歉，並正努力儘速解決問題。你可以查看我們的系統狀態頁面 ，瞭解更多資訊。
如果遇到 InternalServerError，請嘗試以下步驟：
等待幾秒後再重試請求。有時問題可能很快就會解決，請求便可能在第二次嘗試時成功。
查看我們的狀態頁面，確認是否有可能影響服務的事件或維護作業正在進行。如果有尚未解決的事件，請留意最新消息，並等待問題解決後再重試請求。
如果問題持續發生，請參閱「持續發生的錯誤」一節，瞭解後續處理步驟。
我們的支援團隊會調查問題，並儘快回覆你。請注意，由於支援需求量大，等候時間可能較長。你也可以在我們的社群論壇發文 ，但務必移除所有敏感資訊。
RateLimitError RateLimitError 表示你已達到獲配的速率限制。這代表你在特定時間內傳送了過多 Token 或請求，因此我們的服務暫時禁止你繼續傳送。
我們設有速率限制，以確保資源得到公平且有效的運用，並防止服務遭到濫用或負載過重。
如果遇到 RateLimitError，請嘗試以下步驟：
減少傳送的 Token 或請求數量，或放慢傳送速度。你可能需要降低請求的頻率或數量、批次傳送 Token，或在回應未包含 Retry-After 時採用指數退避策略。詳情請參閱我們的速率限制指南 。
如果回應包含 Retry-After，請至少等待其指定的時間後再重試。當伺服器指定的等待時間超過 Python 程式庫支援的上限時，程式庫可能會停止自動重試。如果你在應用程式層級重試，請遵守原本指定的等待時間，並將 SDK 的重試納入考量。
你也可以在帳戶儀表板查看 API 用量統計資料。
如果問題持續發生，請透過線上對話聯絡我們的支援團隊 ，並提供以下資訊：
你當時使用的模型
你收到的錯誤訊息和錯誤碼
你傳送的請求資料和標頭
請求的時間戳記和時區
任何其他可能有助於我們診斷問題的相關詳細資訊
我們的支援團隊會調查問題，並儘快回覆你。請注意，由於支援需求量大，等候時間可能較長。你也可以在我們的社群論壇發文 ，但務必移除所有敏感資訊。
建議你透過程式處理 API 傳回的錯誤。你可以參考以下程式碼片段來實作：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 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 ( "Failed to connect to the OpenAI API:" , error.message);
} else if (error instanceof OpenAI . RateLimitError ) {
console. error ( "OpenAI API request exceeded its rate limit:" , error.message);
} else if (error instanceof OpenAI . APIError ) {
console. error ( "OpenAI API returned an error:" , error.status, error.message);
} else {
throw error;
}
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 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(f"Failed to connect to OpenAI API: {e}")
except openai.RateLimitError as e:
print(f"OpenAI API request exceeded rate limit: {e}")
except openai.APIError as e:
print(f"OpenAI API returned an API Error: {e}")
else:
print(response.output_text) 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 package main
import (
"context"
"errors"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
Model: "gpt-6-astra",
Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Hello world")},
})
if err != nil {
var apiError *openai.Error
if errors.As(err, &apiError) {
fmt.Println("OpenAI API returned an API error:", apiError)
return
}
fmt.Println("Failed to connect to OpenAI API:", err)
return
}
fmt.Println(response.OutputText())
} 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.errors.OpenAIServiceException;
import com.openai.models.responses.ResponseCreateParams;
try {
var response =
client
.responses()
.create(
ResponseCreateParams.builder().model("gpt-6-astra").input("Say hello.").build());
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(text -> System.out.println(text.text()));
} catch (OpenAIServiceException error) {
System.err.println(error.getMessage());
} 1
2
3
4
5
6
7
8
9 require "openai"
client = OpenAI::Client.new
begin
response = client.responses.create(model: "gpt-6-astra", input: "Say hello.")
puts(response.output_text)
rescue OpenAI::Errors::APIError => error
warn(error.message)
end 