API Key 报错排查

API Key 用不了?401、402、403、429 报错怎么解决

AI 的 API Key 为什么突然用不了:401、402、403、429 分别是什么意思,各家供应商余额用完时报哪个码,每种报错怎么解决。

更新于
  • AI 的 API Key「用不了」时,错误码会告诉你原因:401 是 Key 本身不对;402 通常是余额或额度用完了;403 是 Key 没有权限做这件事;429 是请求太多,在某些供应商那里也可能表示余额为零。
  • 各家供应商对「余额用完」用的错误码并不统一:DeepSeek、OpenRouter、Mistral、Together、Fireworks 和 Gemini 的预付费计费用 402;OpenAI、Kimi 和 Z.ai 用 429;阿里云的 Qwen 用 403。别只看数字,要读报错信息。
  • 余额类报错等多久都不会好,限流类报错通常等一会儿就好。下文表格列出了每家供应商的官方错误页面,核验日期为 2026 年 11 月 18 日。
iPhone 上的 Oriveo 供应商页面,列出你已接入的供应商和本月花费。

「API Key 用不了」到底是什么意思?

API Key 是应用每次请求都会带上的密钥,AI 供应商靠它认出是你、该从谁的账户扣费。出问题时,供应商会回一个报错:一个三位数的 HTTP 状态码,加一句简短的说明。

数字告诉你是哪一类问题,说明里有细节。Oriveo 会把常见的报错转成直白的标题,比如「供应商额度已用完」,或网页版的「API Key 无效」(iPhone 和 Android 上是「API 密钥无效」),本页下文有逐条解释。

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

先看这里:找到你的错误码,再去读下面对应的小节。这份速查参照 OpenAI、Anthropic 等供应商截至 2026 年 11 月 18 日的错误页面。

速查:401、402、403、429 和 5xx
错误码通常的意思等一等会好吗?怎么办
401Key 不对:少了字符、多了空格、Key 已删除,或者是别家供应商、别的区域的 Key不会重新复制 Key 或新建一个;检查供应商和区域
402需要付款:预付余额或额度用完了,或者账单出了问题不会充值,或到供应商的账单页面修好支付方式
403Key 有效但没有权限:所在国家或地区不受支持、无权使用该模型,或需要完成验证不会查看支持的地区、Key 的权限,以及有没有待完成的验证
404模型名或地址写错了不会换个模型,或检查地址
429短时间内请求太多;在某些供应商那里,也表示余额为零或触发了消费上限如果是限流,多半会等一会儿再试;如果报错提到 quota、balance、credit 或 spend limit,就去充值或调高上限
500–504、529供应商那边出故障或过载通常会稍后再试,或换个模型

为什么提示余额不足或额度不足(quota)?

大多数供应商要先有预付额度或有效的付款方式,API 才能用,而且每家报「余额用完」的方式都不一样。这类问题换新 Key 都没用,充值才行。

下表是 Oriveo 的 15 家内置供应商各自在文档里写明的「余额或额度用完」时的错误码。「未写明」表示截至 2026 年 11 月 18 日,该供应商的文档没有给出这种情况的 HTTP 状态码。

为什么提示余额不足或额度不足(quota)?
供应商余额用完时的错误码报错信息怎么说官方页面
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
OpenRouter402Your account or API key has insufficient credits(账户或 API Key 的额度不足)openrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balance(余额不足)api-docs.deepseek.com/quick_start/error_codes
xAI(Grok)未写明预付额度用完后,请求会被拒绝docs.x.ai/console/billing
Mistral AI402Payment required(需要付款)docs.mistral.ai/resources/error-glossary
Groq文档未列出Groq 先用后付,错误页面里没有余额类报错console.groq.com/docs/errors
Together AI402Payment Required(需要付款)docs.together.ai/docs/error-codes
Fireworks AI402Payment 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(阿里云)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 Key 无效或认证失败

401 表示供应商不认这个 Key。常见的报错有「Incorrect API key provided」(OpenAI)、「authentication_error」(Anthropic)、「Authentication Fails」(DeepSeek),以及「Invalid API key: this is not an OpenRouter API key」(OpenRouter)。

  • 到供应商网站重新复制 Key,检查有没有漏字符、首尾有没有空格。
  • 确认 Key 属于你选的那家供应商。OpenAI 的 Key 不能当 OpenRouter 的 Key 用,反过来也一样。
  • Kimi、MiniMax 和 Qwen 各自有分区域的平台,一个平台的 Key 在另一个平台上用不了。在 Oriveo 里,到「官方 Endpoint」选择器(iPhone 上叫「官方请求 URL」)选对应的区域。
  • Key 被删除、吊销或已过期的话,新建一个。

402:需要付款(Payment Required)或余额不足

402 跟钱有关:预付余额空了,或者支付方式失败。到供应商的账单页面充值或更新付款信息,再重新发送。干等没用。

在 Oriveo 里它显示为「供应商额度已用完」:「供应商反馈此 API Key 的额度或余额已用完。请到供应商后台检查账单,或切换模型。」

403:禁止访问(Forbidden)或没有权限

403 表示供应商认出了 Key,但不允许这次请求。原因因供应商而异:

  • 在 OpenAI 不支持的国家或地区使用 API 时,OpenAI 会返回「Country, region, or territory not supported」。每家供应商都公布了自己支持的国家和地区列表。
  • Gemini 在这些情况下返回 403:免费层项目需要验证(FREE_TIER_VERIFICATION_REQUIRED)、关联的 Cloud Billing 账户有未付余额,或者 Key 被举报泄露、已被 Google 封禁。
  • Key 无权使用某项资源时,Anthropic 返回 permission_error;请检查你的组织(organization)和工作区(workspace)设置。
  • 请求被权限、内容审核、防护规则(guardrail)或预算上限拦下时,OpenRouter 返回 403。
  • SiliconFlow 的部分模型要求先完成身份验证。
  • Qwen 在账户欠费时用 403;免费额度用完且开启了 Free Quota Only(仅用免费额度)设置时,也会返回 403 AllocationQuota.FreeTierOnly。

429:请求太多、限流或超出额度(quota exceeded)

大多数情况下,429 表示你在短时间内发了太多请求或 token。这是限流(rate limit),等几十秒就会恢复。如果响应里带了 Retry-After 时间,就按它说的等。

也有几家供应商用 429 表示余额为零或触发了消费上限,这种情况等也没用:OpenAI(credit_balance_exhausted,或你自己设的消费上限)、Kimi(exceeded_current_quota_error)、Z.ai(业务码 1113)。Anthropic 的组织达到每月消费上限时也会返回 429(enforced_spend_limit_reached),除非申请更高的档位,否则要等到下个月才恢复。

免费层的限制更紧。Gemini 的免费层和 OpenRouter 的免费模型都有每分钟和每天的限额。

在 Oriveo 里,限流在网页版显示为「频率限制」,在 iPhone 和 Android 上显示为「供应商请求频率受限」。如果报错里提到 quota 或 credit,Oriveo 会改为显示「供应商额度已用完」。

Oriveo 的报错提示是什么意思?

下面是你在 Oriveo 里可能看到的提示,按简体中文界面的原文列出:

Oriveo 的报错提示是什么意思?
Oriveo 显示意思怎么办
已保存,但密钥似乎无效。可稍后在供应商设置中验证。Oriveo 保存了这个供应商,但供应商在检查时拒绝了 Key重新复制 Key,到该供应商的设置里更新
API Key 无效(iPhone、Android 上为「API 密钥无效」)供应商返回了 401 或 403检查或更换 Key;如果是 403,检查区域和权限
供应商额度已用完供应商表示这把 Key 的额度或余额已用完(402,或提到 quota 的 429)到供应商那里充值,或换个模型
频率限制 / 供应商请求频率受限暂时请求太多(429)稍等一下再试
免费额度已用完(Android 上为「免费额度已达上限」)今天的 Oriveo Free 免费额度用完了,跟你自己的 Key 无关添加你自己的 API Key,或等 UTC 00:00 重置
Oriveo 的「供应商」页,列出 OpenAI、Z.ai、Groq、Gemini、Anthropic 等已连接的供应商和各自的花费
在这个列表里打开某个供应商,就能检查或更换它的 Key。

用的是自定义端点、中转站或网关?

如果你通过自定义端点接入,报错可能来自这项服务本身,也可能来自它背后的供应商。Oriveo 提示「这条连接连不上它的上游供应商」时,可能是这项服务自己在供应商那边的账号失效、欠费或被限流了。这不是你的配置问题;换一条连接,或联系这项服务的运营方。

新建 Key 之前,先检查这几项

新 Key 只能解决 401,别的基本帮不上。先把下面过一遍:

  • 供应商选对了;Kimi、MiniMax、Qwen、SiliconFlow 和 Z.ai 还要选对区域。
  • Key 复制完整,没有空格。
  • 账户里有余额,或者有有效的付款方式。
  • 你所在的国家或地区在供应商的支持列表里。
  • 你选的模型对你的账户或档位开放。

应用常见问题

API Key 为什么用不了?
看错误码。401 是 Key 不对;402 是余额或额度用完了;403 是请求不被允许(常见原因是地区或权限);429 是请求太多,在某些供应商那里也可能表示余额为零。
API Key 报 401 是什么意思?
供应商不认这个 Key。重新复制一遍,别带空格;确认它属于你选的供应商和区域;或者新建一个 Key。
402 Payment Required 是什么错误?
预付余额或额度用完了,或者付款出了问题。DeepSeek、OpenRouter、Mistral、Together、Fireworks 和 Gemini 的预付费计费都用这个码。到供应商的账单页面充值;干等没用。
429 是限流还是额度用完了?
两种都有可能。通常是限流,等一会儿就好。但 OpenAI、Kimi 和 Z.ai 在余额为零时也返回 429,所以如果报错提到 quota、balance 或 credit,就去充值,别干等。
OpenAI API Key 为什么提示 insufficient_quota?
你的 OpenAI API 账户没有预付额度了。OpenAI 会返回 429 和错误码 credit_balance_exhausted,错误类型可能仍显示 insufficient_quota。到 OpenAI 的账单设置里充值;换新 Key 没用。
新建的 API Key 复制得没问题,为什么还是用不了?
通常是因为账户还没充值或没设置付款方式、Key 属于另一个区域,或者你所在的国家不在 API 的服务范围内。先查这几项,再考虑新建 Key。

延伸阅读

来自博客

每个报错都给你讲清原因

打开网页版,或下载 iPhone、Android 版 Oriveo,添加 15 家供应商的 Key,请求失败时能看到清楚的原因。

还没有 API Key?可以先用 Oriveo Free 开始。