Gemini API Errors and Fixes: 400, 403, 404, 429, 503 (2026)

Gemini API errors usually come down to a handful of causes: a bad request, a key or billing problem, a wrong model name, a quota hit, or a busy server.

This guide maps every common code to its real fix, using Google’s own troubleshooting and API error pages (updated late October 2026).

You will also get copy-paste Python retry code, the safety and finish_reason blocks explained, and how free tier quotas actually work.

TLDR

Retry only these: 429, 408, 500, 503 and 504, with exponential backoff and jitter.
Never retry these: 400, 402 and 403. Fix the request, credits or billing first.
404 model not found: the model id is wrong, retired, or limited (2.5 models are now limited to recent users).
Quotas are per project, not per key. A new key in the same project will not reset a 429.
Daily limits reset at midnight Pacific time.
Blocked output: check prompt_feedback.block_reason and finish_reason before you assume a bug.

Gemini API Error Codes at a Glance

Every failed call returns an HTTP status and an error object with a code and a message. In streaming mode, the same error arrives as an event with event_type set to "error".

The Python SDK also gives you a status string such as RESOURCE_EXHAUSTED. Here is the full map.

HTTP	Status / code	What it means	Retry?
400	INVALID_ARGUMENT, `invalid_request`, `parameter_unknown`	Malformed body, bad or unknown parameter	No, fix the request
400	FAILED_PRECONDITION	A prerequisite is missing, such as billing	No
401	`authentication`	Key missing, invalid or expired	No
402	`payment_required`	Prepaid credit balance is used up	No, add credits
403	PERMISSION_DENIED	No access, leaked key, free tier unavailable, unpaid balance	No
404	NOT_FOUND, `model_not_found`	Wrong path or model name	No
429	RESOURCE_EXHAUSTED	Per-minute limit, daily quota, or spend cap hit	Yes, with backoff (daily quota: wait)
499	`cancelled`	Your client hung up first	Usually no action
500	INTERNAL, `api_error`	Unexpected server error	Yes
503	UNAVAILABLE	Model overloaded or briefly down	Yes, with backoff
504	DEADLINE_EXCEEDED	Request ran past its deadline	Yes, raise the timeout

Quick answer: Google’s rule is simple. Retry 429, 408 and 5xx with exponential backoff. Do not retry 400, 402 or 403, because they will keep failing until you change something.

400 Errors: Bad Request and Failed Precondition

400 INVALID_ARGUMENT

This means Google could not accept your request body. The usual causes are a typo in a field name, a value out of range, or a feature your model or API version does not support.

Unknown parameter: remove it. Check spelling against the API reference.
Wrong API version: beta features only work on /v1beta, not /v1.
Old sampling settings: Gemini 4 and Gemini 3.6+ ignore temperature, top_p and top_k. They send deprecation warning headers now, and Google says a future release will return 400 errors for them.
candidate_count: not supported on Gemini 3 or Gemini 4 models.
Token limits: check the model page for its max output tokens.

Warning: If your code still sets temperature on Gemini 4, remove it now. It does nothing today, and it is scheduled to become a hard 400 error later.

400 FAILED_PRECONDITION

Something about your account must change before the call can work. Most often that is billing. Link an active billing account in Google AI Studio, then try again.

This can also show up when the free tier is not offered for your project or region. Check the available regions page in the Gemini docs if you are outside the usual markets.

401, 402 and 403: Key, Credits and Billing

401 authentication

Your API key is missing, mistyped or expired. Print the length of the variable (never the key itself) to confirm it loaded. Then copy a fresh key from the API Keys page in Google AI Studio.

402 payment_required

Your prepaid credit balance is empty. Google says plainly: do not retry, because the call will not succeed until credits are added. Top up, or turn on auto-reload.

403 PERMISSION_DENIED

A 403 with “Your project has been denied access” has four common causes. AI Studio may also label the project as Restricted, Free tier unavailable, Payment needed or Unavailable.

Free tier unavailable: not every project qualifies. Eligibility is per Google Cloud project, so a new key in the same project will not help. Link a billing account on the AI Studio billing page.
Payment needed: you have a past-due balance. Fix it on the AI Studio Billing page or the Google Cloud Billing console. Access comes back on its own once the account is in good standing.
Leaked key: the message reads “Your API key was reported as leaked.” Create a new key and replace it everywhere.
Policy suspension: check the email tied to the project and any notice in the Google Cloud console.

Note: A successful models.list call only proves the key exists. It does not prove that generation calls are allowed on that project.

404 Model Not Found

A 404 with model_not_found means the model id in your request does not exist for you. It is the most common error after a model launch or retirement.

Typo or wrong format: use the exact id from the models page, such as gemini-3.8-flash or gemini-4-argon.
Retired model: Gemini 2.0 Flash and 2.0 Flash-Lite shut down on June 1, 2026.
Limited model: since September 18, 2026, Gemini 2.5 models are limited to users who used them recently. New projects should use 3.5 Flash-Lite or 3.8 Flash instead.
Shut-down previews: deep-research-pro-preview-12-2025 shut down on October 23, 2026.

Some deprecated ids are routed for you. Since October 8, 2026, gemini-3.7-flash goes to gemini-3.8-flash, and gemini-3.5-flash goes to gemini-3.6-flash.

Tip: Keep the model id in one config value or environment variable. When Google retires a model, you change one line instead of hunting through code.

429 RESOURCE_EXHAUSTED and Free Tier Quotas

A 429 means you went over a limit. The tricky part is that Gemini has several limits, and crossing any single one triggers the error even if the others are fine.

The limits that can trigger a 429

RPM: requests per minute.
TPM: input tokens per minute.
RPD: requests per day, reset at midnight Pacific time.
IPM: images per minute, for image models.
Spend caps: paid tiers have a rolling 10-minute spend limit ($10 on Tier 1, $50 on Tier 2, $200 on Tier 3).
Tool limits: Grounding with Google Search on Gemini 3 and newer defaults to 1,500 requests per day per project.

Free tier and paid tiers

Limits apply per project, not per API key. Your tier decides how high they go. Exact per-model numbers live on the rate limit page inside Google AI Studio, which Google calls the source of truth.

Tier	How to qualify	Billing cap
Free	Active project or free trial	N/A
Tier 1	Link an active billing account	$250
Tier 2	$100 paid and 3 days since first payment	$2,000
Tier 3	$1,000 paid and 30 days since first payment	$20,000 to $100,000+

Free to Tier 1 is usually instant once billing is linked. Later upgrades apply automatically within about 10 minutes of meeting the rules. Full prices are in my Gemini API pricing and free tier guide.

How to fix a 429

Read the message. It tells you whether you hit a per-minute limit, a daily quota, or a spend cap.
Per-minute limit: retry with exponential backoff and jitter. Spread requests out.
Daily quota: wait for the midnight Pacific reset, or move to a paid tier.
Cut token use: shorten prompts, lower the thinking level, or use context caching.
Use the Batch API for jobs that do not need an instant answer. It has its own, much larger token limits.
Still stuck on a paid tier? Request a higher limit with the form linked from the rate limits page.

Comparing providers? See the LLM API rate limits and tiers comparison.

500, 503 Overloaded and 504 Timeouts

500 INTERNAL

Something broke on Google’s side. Retry with backoff. If the same request fails every time, shrink the input, because a very long context can be the trigger. Contact support if it continues.

503 UNAVAILABLE (the model is overloaded)

This is the “model is overloaded, please try again later” error. It is temporary and not caused by your code. It is most likely at busy times, so the same request often works a few seconds later.

Retry: back off 1s, 2s, 4s, 8s with random jitter.
Fallback model: after a few failures, switch to a lighter model such as a Flash or Flash-Lite variant.
Check status: look at the Google AI Studio status page before you debug your own code.

504 DEADLINE_EXCEEDED

Your request took longer than the deadline allowed. Raise the client timeout, or let the server default apply. Thinking models can take a while on hard prompts, so a short timeout often causes this.

Safety Blocks and finish_reason

Sometimes a call “works” with status 200 but returns no text. That is usually a block, not a bug. Check two places in the generateContent response.

Prompt blocked: prompt_feedback.block_reason

SAFETY: your prompt tripped a safety filter. Check safetyRatings for the category.
BLOCKLIST: it contained a term on the blocklist.
PROHIBITED_CONTENT: it contained prohibited content. This cannot be turned off.
OTHER: it may break the terms of service, or the request is unsupported.

Response stopped: candidates[0].finish_reason

finish_reason	Meaning	Fix
STOP	Normal end	None
MAX_TOKENS	Hit the output token limit	Raise `max_output_tokens` or ask for shorter output
SAFETY	Response flagged by a filter	Reword, or adjust safety settings
RECITATION	Output looked like existing material	Make the prompt and context more unique
LANGUAGE	Unsupported language	Use a supported language
SPII	Possible sensitive personal data	Remove personal details
MALFORMED_FUNCTION_CALL	The model wrote a bad tool call	Simplify the tool schema and retry
MISSING_THOUGHT_SIGNATURE	A thought signature was missing from history	Send back the full previous turns unchanged

Safety settings you can change

You can tune filters for harassment, hate speech, sexually explicit and dangerous content. The levels are Off, Block few, Block some and Block most.

For Gemini 2.5 and later, these extra filters are Off by default. Core protections, such as child safety, always apply and cannot be changed. On the newer Interactions API, a blocked input or output returns an HTTP 400 with a code like safety instead.

Retry Code That Works

Option 1: Let the SDK retry for you

The official google-genai Python SDK already retries timeouts, network errors, 429 and 5xx, up to four times by default. You can tune it with HttpRetryOptions.

from google import genai
from google.genai import types

client = genai.Client(
    http_options=types.HttpOptions(
        retry_options=types.HttpRetryOptions(
            attempts=5,
            initial_delay=1.0,
            max_delay=60.0,
            exp_base=2.0,
            jitter=1.0,
            http_status_codes=[408, 429, 500, 502, 503, 504],
        )
    )
)

resp = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP 429 in one line.",
)
print(resp.text)

Option 2: Your own backoff with a fallback model

Use this when you want logging, a fallback model, and clear handling of blocked output. It reads the API key from the GEMINI_API_KEY environment variable.

import random, time
from google import genai
from google.genai import errors

client = genai.Client()
RETRYABLE = {408, 429, 500, 502, 503, 504}
MODELS = ["gemini-3.8-flash", "gemini-3.5-flash-lite"]

def ask(prompt, max_tries=5):
    for model in MODELS:
        for attempt in range(max_tries):
            try:
                r = client.models.generate_content(model=model, contents=prompt)
                fb = r.prompt_feedback
                if fb and fb.block_reason:
                    raise ValueError(f"Prompt blocked: {fb.block_reason}")
                reason = r.candidates[0].finish_reason
                if "STOP" not in str(reason):
                    print("Finished early:", reason)
                return r.text
            except errors.APIError as e:
                if e.code not in RETRYABLE:
                    raise  # 400, 402, 403, 404: fix, do not retry
                wait = min(60, 2 ** attempt) + random.uniform(0, 1)
                print(f"{model}: {e.code} {e.status}, retry in {wait:.1f}s")
                time.sleep(wait)
        print(f"Giving up on {model}, trying next model")
    raise RuntimeError("All models failed")

print(ask("Give me three tips for clean Python code."))

New to the SDK? My Gemini API Python tutorial covers setup from a free key. For the same patterns on Anthropic’s side, see Claude API errors 429 and 529.

Troubleshooting: Common Problems and Fixes

429 right after creating a new key: limits are per project, so extra keys share the same quota. Slow down, or move the project to a higher tier.
403 even though billing is linked: look for a past-due balance or a payment method problem in the Billing page.
Upgraded to paid but free quota is gone: that is expected. Paid tier usage is billed; it does not add free quota on top.
Empty resp.text: check finish_reason. MAX_TOKENS with thinking models often means the thinking used the budget. Raise the limit or lower the thinking level.
Repeated hyphens or tokens in tables: add table formatting rules and an example to your prompt.
Same text repeating in JSON output: do not set field order in the prompt, and make all schema fields required.
Odd or blocked replies in some languages: the API supports a fixed set of languages. Check the model page.
Surprise charges from a leaked key: rotate the key, then open a billing support case in the Google Cloud console.

Warning: Never put a Gemini API key in browser JavaScript or a public repo. Google actively blocks keys reported as leaked, and your app will start returning 403.

Frequently Asked Questions

What does 429 RESOURCE_EXHAUSTED mean in the Gemini API?

You crossed a rate limit, a daily quota or a spend cap for your project. Back off and retry for per-minute limits, or wait for the midnight Pacific reset for daily quotas.

Why do I get 503 “model is overloaded”?

Google’s servers for that model are busy. It is temporary, so retry with exponential backoff and jitter, and fall back to a lighter model if it keeps happening.

Does creating a new API key reset my Gemini quota?

No. Rate limits are applied per Google Cloud project, not per API key. Only a higher usage tier raises your limits.

How do I fix 404 model not found?

Check the exact model id on the Gemini models page. The model may be misspelled, retired, or limited, as Gemini 2.5 models now are for new users.

Should I retry a 400 or 403 error?

No. Google says not to retry 400, 402 or 403 errors. Fix the request, add credits, or resolve billing first.

Why is my Gemini response empty with no error?

The prompt or response was probably blocked. Check prompt_feedback.block_reason and candidates[0].finish_reason for SAFETY, RECITATION or MAX_TOKENS.

When do Gemini daily limits reset?

Requests-per-day quotas reset at midnight Pacific time. Per-minute limits recover within a minute.

Gemini API Errors and Fixes (2026): 400, 403, 404, 429 RESOURCE_EXHAUSTED, 503 Overloaded and Safety Blocks

Gemini API Error Codes at a Glance