本指南整理了使用 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 service_tier argument: The requested service tier is not allowed for this project.」,錯誤類型為 invalid_request_error,而 error.param 的值為 service_tier。
專案限制適用於 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,除非也已達各自的上限或組織上限。
若要恢復 API 存取權,請在專案設定 中提高或移除上限。若未調整,每月上限重設後即可恢復存取。
429 - 已達組織用量上限 organization_usage_limit_exceeded 錯誤表示組織已達 OpenAI 核定的每月用量上限 。這項上限與你設定的組織和專案支出上限各自獨立。
若要恢復 API 存取權,請申請提高核准的用量上限 ,或聯絡支援團隊 。
503 - 模型暫時超載 如果收到 503 回應,且錯誤類型為 service_unavailable_error、代碼為 server_is_overloaded,表示你指定的模型目前沒有足夠容量處理這項請求。
如果回應包含 Retry-After 標頭,請至少等候標頭指定的時間再重試。如果沒有該標頭,請拉長重試間隔。如果錯誤持續發生,請查看系統狀態頁面 ,確認是否有尚未排除的事件。
Python 函式庫引發的 RateLimitError 對應 429 回應,InternalServerError 則對應 503 回應。如果你的錯誤處理程式先前只捕捉其中一種例外來處理限流和超載,請改為處理兩種例外,並檢查 error.code。例如,影片端點超載時,現在會傳回 503,先前則是傳回 429。各端點的變更請參閱遷移指南 。
類型
說明
APIConnectionError
原因: 連線至我們的服務時發生問題。 解決方法: 檢查網路設定、Proxy 設定、SSL 憑證或防火牆規則。
APITimeoutError
原因: 請求逾時。 解決方法: 稍候再重試請求。如果問題持續發生,請聯絡我們。
AuthenticationError
原因: API 金鑰或權杖無效、已過期或已撤銷。 解決方法: 檢查 API 金鑰或權杖,確認內容正確且仍有效。你可能需要從帳戶儀表板產生新的金鑰或權杖。
BadRequestError
原因: 請求格式有誤,或缺少權杖、輸入內容等必要參數。 解決方法: 錯誤訊息通常會指出具體問題。請查看所呼叫 API 方法的文件 ,確認傳送的參數有效且完整。你可能也需要檢查請求資料的編碼、格式或大小。
ConflictError
原因: 另一個請求已更新該資源。 解決方法: 再次嘗試更新資源,並確認沒有其他請求同時嘗試更新。
InternalServerError
原因: 我們的系統發生問題。 解決方法: 稍候再重試請求。如果問題持續發生,請聯絡我們。
NotFoundError
原因: 請求的資源不存在。 解決方法: 確認使用的資源識別碼正確。
PermissionDeniedError
原因: 你沒有存取所請求資源的權限。 解決方法: 確認使用的 API 金鑰、組織 ID 和資源 ID 正確。
RateLimitError
原因: 你已達獲配的速率限制,或流量增加過快。 解決方法: 控制傳送請求的頻率。如果回應包含 Retry-After,請依照指定時間等候,並遵守重試次數限制。詳情請參閱速率限制指南 。
UnprocessableEntityError
原因: 請求格式正確,但系統無法處理。 解決方法: 請重試請求。
APIConnectionError APIConnectionError 表示你的請求無法送達我們的伺服器,或無法建立安全連線。問題可能與網路、Proxy 設定、SSL 憑證或防火牆規則有關。
如果遇到 APIConnectionError,請嘗試下列步驟:
檢查網路設定,確認網際網路連線穩定且速度足夠。你可能需要切換網路、改用有線連線,或減少占用頻寬的裝置或應用程式數量。
檢查 Proxy 設定,確認與我們的服務相容。你可能需要更新設定、改用其他 Proxy,或直接連線而不經過 Proxy。
檢查 SSL 憑證,確認憑證有效且為最新版本。你可能需要安裝或更新憑證、改用其他憑證授權單位,或停用 SSL 驗證。
檢查防火牆規則,確認沒有封鎖或過濾我們服務的流量。你可能需要修改防火牆設定。
如果使用容器,請確認容器具備傳送及接收流量所需的權限。
如果問題持續發生,請參閱「持續發生的錯誤」一節,瞭解後續步驟。
APITimeoutError APITimeoutError 表示請求耗時過長,因此我們的伺服器已關閉連線。可能是網路出現問題、我們的服務負載過高,或請求較複雜,需要更多處理時間。
如果遇到 APITimeoutError,請嘗試下列步驟:
等候幾秒後重試請求。網路壅塞或服務負載有時會在這段時間內緩解,第二次嘗試就可能成功。
檢查網路設定,確認網際網路連線穩定且速度足夠。你可能需要切換網路、改用有線連線,或減少占用頻寬的裝置或應用程式數量。
如果問題持續發生,請參閱「持續發生的錯誤」一節,瞭解後續步驟。
AuthenticationError AuthenticationError 表示 API 金鑰或權杖無效、已過期或已撤銷。可能原因包括輸入錯字、格式錯誤或資安事件。
如果遇到 AuthenticationError,請嘗試下列步驟:
檢查 API 金鑰或權杖,確認內容正確且仍有效。你可能需要從 API 金鑰儀表板產生新金鑰,或確認沒有多餘的空格或字元。如果有多組金鑰或權杖,也可以改用另一組。
確認使用的格式正確。
BadRequestError BadRequestError(舊稱 InvalidRequestError)表示請求格式有誤,或缺少權杖、輸入內容等必要參數。可能原因包括輸入錯字、格式錯誤或程式碼中的邏輯錯誤。
如果遇到 BadRequestError,請嘗試下列步驟:
仔細閱讀錯誤訊息,找出具體問題。訊息通常會指出哪個參數無效或缺漏,以及預期的值或格式。
在 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