API key troubleshooting

API Key Not Working? Fix 401, 402, 403 and 429 Errors

Why an AI API key stops working: what 401, 402, 403 and 429 mean, which code each provider uses for an empty balance, and how to fix each one.

Updated
  • When an AI API key "isn’t working", the error number tells you why: 401 means the key itself is wrong, 402 usually means your balance or credits have run out, 403 means the key isn’t allowed to do that, and 429 means too many requests or, with some providers, an empty balance.
  • Providers don’t agree on the code for an empty balance. DeepSeek, OpenRouter, Mistral, Together, Fireworks and Gemini’s prepaid billing use 402; OpenAI, Kimi and Z.ai use 429; Alibaba Cloud’s Qwen uses 403. Read the message, not just the number.
  • Balance errors don’t go away if you wait; rate limits usually do. The table below lists each provider’s official error page, checked on 18 November 2026.
Oriveo on iPhone: the providers screen, listing the providers you connected and this month’s spend.

What does "API key not working" actually mean?

An API key is the secret code an app sends with each request so the AI provider knows it’s you and whose account to charge. When something goes wrong, the provider replies with an error: a three-digit number called an HTTP status code, plus a short message.

The number tells you what kind of problem it is; the message gives the detail. Oriveo turns the common ones into plain titles such as "Invalid API Key" or "Provider Quota Reached", explained further down this page.

Quick guide: 401, 402, 403, 429 and 5xx

Start here. Find your number, then read the matching section below. This summary follows the error pages of OpenAI, Anthropic and other providers as of 18 November 2026.

Quick guide: 401, 402, 403, 429 and 5xx
CodeWhat it usually meansWill waiting fix it?What to do
401The key is wrong: a missing character, an extra space, a deleted key, or a key from another provider or regionNoCopy the key again or create a new one; check the provider and region
402Payment needed: your prepaid balance or credits ran out, or there’s a billing problemNoTop up, or fix the payment method on the provider’s billing page
403The key works but isn’t allowed: unsupported country or region, no access to that model, or a verification stepNoCheck supported regions, the key’s permissions and any verification
404The model name or address is wrongNoPick another model or check the address
429Too many requests in a short time or, with some providers, an empty balance or a spending limitOften, if it’s a rate limitWait and retry; if the message mentions quota, balance, credit or spend limit, top up or raise the limit
500–504, 529A fault or overload on the provider’s sideUsuallyTry again later or switch models

Why does it say insufficient balance or quota?

Most providers need prepaid credit or an active billing method before the API works, and each one reports an empty balance in its own way. A new key won’t fix any of these; adding credit will.

This is the code each of Oriveo’s 15 built-in providers documents when your balance or credit runs out. "Not stated" means the provider’s documentation, checked on 18 November 2026, doesn’t give an HTTP code for this case.

Why does it say insufficient balance or quota?
ProviderCode when your balance runs outWhat the message saysOfficial page
OpenAI429credit_balance_exhausted (the error type may still read insufficient_quota)developers.openai.com/api/docs/guides/error-codes
Anthropic (Claude)Not stated"Your credit balance is too low to access the Anthropic API"; payment problems return 402 billing_errorplatform.claude.com/docs/en/api/errors (codes); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (message)
Google Gemini402 (prepaid billing)payment_required; 403 can also mean an unpaid Cloud Billing balanceaistudio.google.com/docs/api-errors
OpenRouter402Your account or API key has insufficient creditsopenrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)Not statedRequests are rejected once prepaid credits run outdocs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
GroqNot documentedGroq bills after use; its error page lists no balance errorconsole.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMaxNot stated (business code 1008)insufficient balanceplatform.minimax.io/docs/api-reference/errorcode
Z.ai (GLM)429 (code 1113)Insufficient balance or no resource package. Please recharge.docs.z.ai/api-reference/api-code
Qwen (Alibaba Cloud)403Arrearage or isv.OUT_OF_SERVICE (account in arrears)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlowNot documentedNo balance error listeddocs.siliconflow.com/en/faqs/error-code

401: invalid API key or authentication failed

A 401 means the provider doesn’t recognise the key. Typical messages are "Incorrect API key provided" (OpenAI), "authentication_error" (Anthropic), "Authentication Fails" (DeepSeek) and "Invalid API key: this is not an OpenRouter API key" (OpenRouter).

  • Copy the key again from the provider’s site, and check for missing characters or spaces at either end.
  • Make sure the key belongs to the provider you chose. An OpenAI key won’t work as an OpenRouter key, and the other way round.
  • Kimi, MiniMax and Qwen run separate regional platforms, and a key from one doesn’t work on another. In Oriveo, choose the matching region in the "Official Endpoint" selector ("Official Request URL" on iPhone).
  • If the key was deleted, revoked or has expired, create a new one.

402: payment required or insufficient balance

A 402 is about money: the prepaid balance is empty, or the payment method failed. Top up or update your payment details on the provider’s billing page, then send again. Waiting doesn’t help.

In Oriveo this appears as "Provider Quota Reached": "The provider reports that the quota or credit for this API key is used up. Check your billing with the provider, or switch models."

403: forbidden or permission denied

A 403 means the provider recognised the key but won’t allow the request. The reason depends on the provider:

  • OpenAI returns "Country, region, or territory not supported" when the API is used from a country it doesn’t support. Each provider publishes its list of supported countries.
  • Gemini returns 403 when a free-tier project needs verification (FREE_TIER_VERIFICATION_REQUIRED), when the linked Cloud Billing account has an unpaid balance, or when Google has blocked a key reported as leaked.
  • Anthropic returns permission_error when the key can’t use the resource; check your organisation and workspace settings.
  • OpenRouter returns 403 when a request is blocked by permissions, moderation, a guardrail or a budget limit.
  • SiliconFlow requires identity verification for some models.
  • Qwen uses 403 for an account in arrears, and for AllocationQuota.FreeTierOnly when the free quota is used up and the "Free Quota Only" setting is on.

429: too many requests, rate limit or quota exceeded

Most of the time, 429 means you sent too many requests or tokens in a short time. That is a rate limit, and it clears if you wait a few tens of seconds. If the reply includes a Retry-After time, wait that long.

Several providers also use 429 for an empty balance or a spending limit, and waiting won’t fix those: OpenAI (credit_balance_exhausted, or a spend limit you set), Kimi (exceeded_current_quota_error), Z.ai (code 1113), and Anthropic when an organisation reaches its monthly spend limit (enforced_spend_limit_reached), which lasts until the next month unless you request a higher tier.

Free tiers are tighter. Gemini’s free tier and OpenRouter’s free models have per-minute and per-day limits.

In Oriveo, a rate limit appears as "Rate Limited" on the web or "Provider Rate Limited" on iPhone and Android. If the message mentions quota or credit, Oriveo shows "Provider Quota Reached" instead.

What do Oriveo’s error messages mean?

These are the messages you may see in Oriveo, in its English wording:

What do Oriveo’s error messages mean?
What Oriveo showsWhat it meansWhat to do
Saved, but the key looks invalid. You can verify it later in provider settings.Oriveo saved the provider, but the provider rejected the key during the checkCopy the key again and update it in that provider’s settings
Invalid API KeyThe provider returned 401 or 403Check or replace the key; for 403, check region and permissions
Provider Quota ReachedThe provider says the credit or quota for this key is used up (402, or 429 mentioning quota)Top up with the provider, or switch to another model
Rate Limited / Provider Rate LimitedToo many requests for now (429)Wait a moment and try again
Free Quota ReachedToday’s Oriveo Free allowance is used up; this has nothing to do with your own keyAdd your own API key, or wait for the reset at 00:00 UTC
Oriveo Providers screen listing connected providers such as OpenAI, Z.ai, Groq, Gemini and Anthropic, each with its spend
Open a provider from this list to check or replace its key.

Using a custom endpoint, relay or gateway?

If you connect through a custom endpoint, the error can come from that service or from the provider behind it. When Oriveo says "This connection could not reach its upstream provider", the service’s own account with the provider may be invalid, out of credits or rate-limited. That isn’t your configuration; switch to another connection or contact whoever runs the service.

Check these before you create a new key

A new key fixes a 401 and little else. Go through this list first:

  • You chose the right provider and, for Kimi, MiniMax, Qwen, SiliconFlow and Z.ai, the right region.
  • You copied the whole key, with no spaces.
  • There is credit in the account, or an active billing method.
  • Your country or region is on the provider’s supported list.
  • The model you picked is available to your account or tier.

Common app questions

Why is my API key not working?
Look at the error number. 401 means the key is wrong, 402 means your balance or credits ran out, 403 means the request isn’t allowed (often region or permissions), and 429 means too many requests or, with some providers, an empty balance.
What does a 401 error mean for an API key?
The provider doesn’t recognise the key. Copy it again without spaces, check that it belongs to the provider and region you chose, or create a new key.
What is a 402 Payment Required error?
Your prepaid balance or credits have run out, or there’s a payment problem. DeepSeek, OpenRouter, Mistral, Together, Fireworks and Gemini’s prepaid billing use it. Top up on the provider’s billing page; waiting won’t fix it.
Is a 429 error a rate limit or a quota problem?
It can be either. Usually it’s a rate limit that clears after a short wait. But OpenAI, Kimi and Z.ai also return 429 when your balance is empty, so if the message mentions quota, balance or credit, add credit instead of waiting.
Why does my OpenAI API key say insufficient_quota?
Your OpenAI API account has no prepaid credit left. OpenAI returns 429 with the code credit_balance_exhausted, and the error type may still say insufficient_quota. Add credit in OpenAI’s billing settings; a new key won’t help.
Why doesn’t my new API key work when I copied it correctly?
Usually because the account has no credit yet or billing isn’t set up, the key belongs to a different region, or the API isn’t offered in your country. Check those before creating another key.

Related reads

From the blog

See plain-language errors for every key

Open the web app or download Oriveo for iPhone or Android, add keys from 15 providers, and get a clear reason when a request fails.

No API key yet? Oriveo Free lets you start without one.