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 日。

「API 金鑰不能用」到底是什麼意思?
API 金鑰(API key)是 App 每次發出請求時附上的祕密代碼,讓 AI 供應商知道是你、該向哪個帳戶收費。出問題時,供應商會回傳一個錯誤:一個三位數的數字,叫做 HTTP 狀態碼,再加上一段簡短訊息。
數字告訴你是哪一類問題,訊息則提供細節。Oriveo 會把常見的錯誤換成好懂的標題,例如「API 金鑰無效」或「供應商額度已用完」,本頁下方會再說明。
速查:401、402、403、429 和 5xx
從這裡開始。找到你的代碼,再看下方對應的段落。這份摘要依據 2026 年 11 月 18 日 OpenAI、Anthropic 等供應商的錯誤說明頁整理。
| 代碼 | 通常代表 | 等一下會好嗎? | 怎麼處理 |
|---|---|---|---|
| 401 | 金鑰有誤:少了字元、多了空格、金鑰已刪除,或是別家供應商、別的區域的金鑰 | 不會 | 重新複製金鑰或建立新的;確認供應商和區域 |
| 402 | 需要付款:預付餘額或 credits 用完了,或是帳單出了問題 | 不會 | 儲值,或到供應商的帳單頁面修正付款方式 |
| 403 | 金鑰有效但不被允許:所在國家或地區不支援、沒有該模型的權限,或需要完成驗證 | 不會 | 確認支援的地區、金鑰的權限,以及是否有待完成的驗證 |
| 404 | 模型名稱或網址錯誤 | 不會 | 換一個模型,或檢查網址 |
| 429 | 短時間內請求太多;有些供應商也用它表示餘額用完或達到消費上限 | 如果是速率限制,通常會 | 等一下再試;如果訊息提到 quota、balance、credit 或 spend limit,就要儲值或調高上限 |
| 500–504、529 | 供應商那邊故障或過載 | 通常會 | 稍後再試,或換一個模型 |
為什麼顯示餘額不足或額度用完?
大多數供應商要先有預付額度或有效的付款方式,API 才能使用,而且每家回報餘額用完的方式都不一樣。換新金鑰解決不了這些問題;儲值才行。
下表是 Oriveo 15 家內建供應商在餘額或 credits 用完時,各自文件記載的代碼。「未說明」表示截至 2026 年 11 月 18 日,該供應商的文件沒有為這種情況寫出 HTTP 代碼。
| 供應商 | 餘額用完時的代碼 | 訊息內容 | 官方頁面 |
|---|---|---|---|
| OpenAI | 429 | credit_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_error | platform.claude.com/docs/en/api/errors(代碼);platform.claude.com/docs/en/about-claude/api-credits-for-subscribers(訊息) |
| Google Gemini | 402(預付計費) | payment_required;403 也可能代表 Cloud Billing 帳戶有未繳款項 | aistudio.google.com/docs/api-errors |
| OpenRouter | 402 | 帳戶或 API 金鑰的 credits 不足 | openrouter.ai/docs/api-reference/errors |
| DeepSeek | 402 | Insufficient Balance | api-docs.deepseek.com/quick_start/error_codes |
| xAI(Grok) | 未說明 | 預付 credits 用完後,請求會被拒絕 | docs.x.ai/console/billing |
| Mistral AI | 402 | Payment required | docs.mistral.ai/resources/error-glossary |
| Groq | 文件未列出 | Groq 採用後付費;錯誤說明頁沒有列出餘額相關錯誤 | console.groq.com/docs/errors |
| Together AI | 402 | Payment Required | docs.together.ai/docs/error-codes |
| Fireworks AI | 402 | Payment Required | docs.fireworks.ai/guides/inference-error-codes |
| MiniMax | 未說明(業務代碼 1008) | insufficient balance | platform.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) | 403 | Arrearage 或 isv.OUT_OF_SERVICE(帳戶欠費) | alibabacloud.com/help/en/model-studio/error-code |
| Kimi(Moonshot AI) | 429 | exceeded_current_quota_error | platform.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 已儲存這個供應商,但檢查時供應商拒絕了金鑰 | 重新複製金鑰,到該供應商的設定裡更新 |
| API 金鑰無效 | 供應商回傳了 401 或 403 | 檢查或更換金鑰;如果是 403,請確認區域和權限 |
| 供應商額度已用完 | 供應商表示這把金鑰的 credit 或額度已用完(402,或提到 quota 的 429) | 向供應商儲值,或換一個模型 |
| 頻率限制(網頁版)/供應商請求頻率受限(iPhone、Android) | 目前請求太多(429) | 稍等一下再試 |
| 免費額度已用完(網頁版、iPhone)/免費額度已達上限(Android) | 今天的 Oriveo Free 額度用完了,跟你自己的金鑰無關 | 加入自己的 API 金鑰,或等 UTC 00:00 重置 |

使用自訂端點、中轉站或閘道?
如果你是透過自訂端點連線,錯誤可能來自那個服務,也可能來自它背後的供應商。當 Oriveo 顯示「這條連線連不上它的上游供應商。」時,代表該服務自己在供應商那邊的帳戶可能已失效、credits 用完或被限流。這不是你的設定問題;請改用另一條連線,或聯絡這項服務的營運者。
建立新金鑰之前,先檢查這幾項
新金鑰只能解決 401,其他問題幾乎都幫不上忙。先把這份清單過一遍:
- 選對了供應商;如果是 Kimi、MiniMax、Qwen、SiliconFlow 和 Z.ai,也要選對區域。
- 完整複製了金鑰,沒有多出空格。
- 帳戶裡有餘額,或有有效的付款方式。
- 你所在的國家或地區在供應商的支援清單上。
- 你選的模型有開放給你的帳戶或級別使用。