API Key 錯誤排解

API 金鑰不能用?401、402、403、429 錯誤原因與解法

AI 的 API 金鑰(API key)為什麼突然不能用?看懂 401、402、403、429 的意思、各家供應商餘額用完時回傳哪個代碼,以及每種錯誤怎麼解決。

更新於
  • AI 的 API 金鑰「不能用」時,錯誤代碼會告訴你原因:401 是金鑰本身有誤;402 通常是餘額或 credits 用完了;403 是這把金鑰不被允許做這件事;429 是請求太多,有些供應商也用它表示餘額用完。
  • 餘額用完時回傳哪個代碼,各家供應商並不一致。DeepSeek、OpenRouter、Mistral、Together、Fireworks 和 Gemini 的預付計費用 402;OpenAI、Kimi 和 Z.ai 用 429;Alibaba Cloud 的 Qwen 用 403。請看錯誤訊息的內容,不要只看數字。
  • 餘額不足的錯誤不會因為等待而消失,速率限制通常會。下方表格列出各家供應商的官方錯誤說明頁,核對日期為 2026 年 11 月 18 日。
iPhone 上的 Oriveo:供應商頁面,列出你已連接的供應商和本月花費。

「API 金鑰不能用」到底是什麼意思?

API 金鑰(API key)是 App 每次發出請求時附上的祕密代碼,讓 AI 供應商知道是你、該向哪個帳戶收費。出問題時,供應商會回傳一個錯誤:一個三位數的數字,叫做 HTTP 狀態碼,再加上一段簡短訊息。

數字告訴你是哪一類問題,訊息則提供細節。Oriveo 會把常見的錯誤換成好懂的標題,例如「API 金鑰無效」或「供應商額度已用完」,本頁下方會再說明。

速查:401、402、403、429 和 5xx

從這裡開始。找到你的代碼,再看下方對應的段落。這份摘要依據 2026 年 11 月 18 日 OpenAI、Anthropic 等供應商的錯誤說明頁整理。

速查:401、402、403、429 和 5xx
代碼通常代表等一下會好嗎?怎麼處理
401金鑰有誤:少了字元、多了空格、金鑰已刪除,或是別家供應商、別的區域的金鑰不會重新複製金鑰或建立新的;確認供應商和區域
402需要付款:預付餘額或 credits 用完了,或是帳單出了問題不會儲值,或到供應商的帳單頁面修正付款方式
403金鑰有效但不被允許:所在國家或地區不支援、沒有該模型的權限,或需要完成驗證不會確認支援的地區、金鑰的權限,以及是否有待完成的驗證
404模型名稱或網址錯誤不會換一個模型,或檢查網址
429短時間內請求太多;有些供應商也用它表示餘額用完或達到消費上限如果是速率限制,通常會等一下再試;如果訊息提到 quota、balance、credit 或 spend limit,就要儲值或調高上限
500–504、529供應商那邊故障或過載通常會稍後再試,或換一個模型

為什麼顯示餘額不足或額度用完?

大多數供應商要先有預付額度或有效的付款方式,API 才能使用,而且每家回報餘額用完的方式都不一樣。換新金鑰解決不了這些問題;儲值才行。

下表是 Oriveo 15 家內建供應商在餘額或 credits 用完時,各自文件記載的代碼。「未說明」表示截至 2026 年 11 月 18 日,該供應商的文件沒有為這種情況寫出 HTTP 代碼。

為什麼顯示餘額不足或額度用完?
供應商餘額用完時的代碼訊息內容官方頁面
OpenAI429credit_balance_exhausted(錯誤類型可能仍顯示 insufficient_quota)developers.openai.com/api/docs/guides/error-codes
Anthropic(Claude)未說明「Your credit balance is too low to access the Anthropic API」;付款問題則回傳 402 billing_errorplatform.claude.com/docs/en/api/errors(代碼);platform.claude.com/docs/en/about-claude/api-credits-for-subscribers(訊息)
Google Gemini402(預付計費)payment_required;403 也可能代表 Cloud Billing 帳戶有未繳款項aistudio.google.com/docs/api-errors
OpenRouter402帳戶或 API 金鑰的 credits 不足openrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI(Grok)未說明預付 credits 用完後,請求會被拒絕docs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
Groq文件未列出Groq 採用後付費;錯誤說明頁沒有列出餘額相關錯誤console.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMax未說明(業務代碼 1008)insufficient balanceplatform.minimax.io/docs/api-reference/errorcode
Z.ai(GLM)429(代碼 1113)Insufficient balance or no resource package. Please recharge.docs.z.ai/api-reference/api-code
Qwen(Alibaba Cloud)403Arrearage 或 isv.OUT_OF_SERVICE(帳戶欠費)alibabacloud.com/help/en/model-studio/error-code
Kimi(Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlow文件未列出沒有列出餘額相關錯誤docs.siliconflow.com/en/faqs/error-code

401:API 金鑰無效或驗證失敗

401 代表供應商不認得這把金鑰。常見訊息有「Incorrect API key provided」(OpenAI)、「authentication_error」(Anthropic)、「Authentication Fails」(DeepSeek),以及「Invalid API key: this is not an OpenRouter API key」(OpenRouter)。

  • 回供應商網站重新複製金鑰,檢查有沒有少了字元,或頭尾多了空格。
  • 確認金鑰屬於你選的那家供應商。OpenAI 的金鑰不能當 OpenRouter 金鑰用,反過來也一樣。
  • Kimi、MiniMax 和 Qwen 各有獨立的區域平台,一個平台的金鑰不能在另一個平台使用。在 Oriveo 裡,請在「官方 Endpoint」選單中選擇對應的區域(iPhone 上叫「官方請求 URL」)。
  • 如果金鑰已被刪除、撤銷或過期,就建立一把新的。

402:需要付款或餘額不足

402 跟錢有關:預付餘額用完了,或付款方式失敗。到供應商的帳單頁面儲值或更新付款資料,再重新送出。等待沒有用。

在 Oriveo 裡,這會顯示為「供應商額度已用完」:「供應商回報此 API 金鑰的額度或餘額已用完。請到供應商後台檢查帳單,或切換模型。」

403:禁止存取或權限不足

403 代表供應商認得這把金鑰,但不允許這個請求。原因依供應商而定:

  • 從 OpenAI 不支援的國家使用 API 時,OpenAI 會回傳「Country, region, or territory not supported」。各家供應商都有公布自己支援的國家清單。
  • Gemini 在以下情況回傳 403:免費層專案需要驗證(FREE_TIER_VERIFICATION_REQUIRED)、連結的 Cloud Billing 帳戶有未繳款項,或 Google 封鎖了被回報外洩的金鑰。
  • Anthropic 在金鑰無法使用該資源時回傳 permission_error;請檢查你的組織(organization)和工作區(workspace)設定。
  • OpenRouter 在請求被權限、內容審核、防護規則或預算上限擋下時回傳 403。
  • SiliconFlow 的部分模型需要先完成身分驗證。
  • Qwen 在帳戶欠費時回傳 403;免費額度用完、而且開啟了「Free Quota Only」設定時,也會回傳 403 和 AllocationQuota.FreeTierOnly。

429:請求太多、速率限制或超出額度

大多數時候,429 代表你在短時間內送出太多請求或 token。這是速率限制,等幾十秒就會解除。如果回應裡帶有 Retry-After 時間,就等那麼久。

也有幾家供應商用 429 表示餘額用完或達到消費上限,這種情況等待沒有用:OpenAI(credit_balance_exhausted,或你自己設定的消費上限)、Kimi(exceeded_current_quota_error)、Z.ai(代碼 1113),以及 Anthropic 的組織達到每月消費上限時(enforced_spend_limit_reached),這會一直持續到下個月,除非你申請更高的級別(tier)。

免費層的限制更嚴。Gemini 的免費層和 OpenRouter 的免費模型都有每分鐘和每日上限。

在 Oriveo 裡,速率限制在網頁版顯示為「頻率限制」,在 iPhone 和 Android 上顯示為「供應商請求頻率受限」。如果訊息提到 quota 或 credit,Oriveo 會改為顯示「供應商額度已用完」。

Oriveo 的錯誤訊息是什麼意思?

以下是你在 Oriveo 繁體中文介面上可能看到的訊息:

Oriveo 的錯誤訊息是什麼意思?
Oriveo 顯示代表什麼怎麼處理
已儲存,但金鑰似乎無效。可稍後在供應商設定中驗證。Oriveo 已儲存這個供應商,但檢查時供應商拒絕了金鑰重新複製金鑰,到該供應商的設定裡更新
API 金鑰無效供應商回傳了 401 或 403檢查或更換金鑰;如果是 403,請確認區域和權限
供應商額度已用完供應商表示這把金鑰的 credit 或額度已用完(402,或提到 quota 的 429)向供應商儲值,或換一個模型
頻率限制(網頁版)/供應商請求頻率受限(iPhone、Android)目前請求太多(429)稍等一下再試
免費額度已用完(網頁版、iPhone)/免費額度已達上限(Android)今天的 Oriveo Free 額度用完了,跟你自己的金鑰無關加入自己的 API 金鑰,或等 UTC 00:00 重置
Oriveo 的「供應商」頁面,列出已連接的供應商,例如 OpenAI、Z.ai、Groq、Gemini 和 Anthropic,各自顯示花費
從這份清單點進某個供應商,就能檢查或更換它的金鑰。

使用自訂端點、中轉站或閘道?

如果你是透過自訂端點連線,錯誤可能來自那個服務,也可能來自它背後的供應商。當 Oriveo 顯示「這條連線連不上它的上游供應商。」時,代表該服務自己在供應商那邊的帳戶可能已失效、credits 用完或被限流。這不是你的設定問題;請改用另一條連線,或聯絡這項服務的營運者。

建立新金鑰之前,先檢查這幾項

新金鑰只能解決 401,其他問題幾乎都幫不上忙。先把這份清單過一遍:

  • 選對了供應商;如果是 Kimi、MiniMax、Qwen、SiliconFlow 和 Z.ai,也要選對區域。
  • 完整複製了金鑰,沒有多出空格。
  • 帳戶裡有餘額,或有有效的付款方式。
  • 你所在的國家或地區在供應商的支援清單上。
  • 你選的模型有開放給你的帳戶或級別使用。

App 常見問題

API 金鑰為什麼不能用?
看錯誤代碼。401 是金鑰有誤;402 是餘額或 credits 用完了;403 是請求不被允許(常見原因是地區或權限);429 是請求太多,有些供應商也用它表示餘額用完。
API 金鑰出現 401 錯誤是什麼意思?
供應商不認得這把金鑰。重新複製,注意不要帶到空格;確認它屬於你選的供應商和區域,或建立一把新金鑰。
402 Payment Required 錯誤是什麼?
你的預付餘額或 credits 用完了,或付款出了問題。DeepSeek、OpenRouter、Mistral、Together、Fireworks 和 Gemini 的預付計費都用這個代碼。到供應商的帳單頁面儲值;等待不會好。
429 錯誤是速率限制還是額度問題?
兩種都有可能。通常是速率限制,稍等一下就會解除。但 OpenAI、Kimi 和 Z.ai 在餘額用完時也會回傳 429,所以如果訊息提到 quota、balance 或 credit,就該儲值,而不是等待。
OpenAI API 金鑰為什麼顯示 insufficient_quota?
你的 OpenAI API 帳戶沒有預付額度了。OpenAI 會回傳 429 和代碼 credit_balance_exhausted,錯誤類型可能仍顯示 insufficient_quota。到 OpenAI 的帳單設定儲值;換新金鑰沒有用。
新金鑰明明複製對了,為什麼還是不能用?
通常是帳戶還沒有額度或還沒設定付款、金鑰屬於另一個區域,或你所在的國家不在 API 的服務範圍內。建立另一把金鑰之前,先檢查這幾點。

延伸閱讀

來自部落格

每把金鑰出錯,都用白話告訴你原因

打開網頁版,或下載 iPhone、Android 版 Oriveo,加入 15 家供應商的金鑰,請求失敗時看得到清楚的原因。

還沒有 API 金鑰?先用 Oriveo Free 免費開始也可以。