Gemini API key not working — API_KEY_INVALID and its five causes

"API key not valid. Please pass a valid API key." — Gemini's least helpful sentence. The key usually IS valid; something around it is wrong: a referrer restriction, the Generative Language API not enabled, or an AI-Studio key sent to a Vertex endpoint. Work the list below in order.

The error

response (HTTP 400)

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [{ "reason": "API_KEY_INVALID" }]
  }
}

Causes and fixes at a glance

Cause	Fix
Key restrictions (HTTP referrer / IP) blocking server calls	In Google Cloud Console → Credentials, a referrer-restricted key rejects server-side requests. Use an unrestricted key or restrict by API instead.
Generative Language API not enabled on the project	Enable "Generative Language API" for AI-Studio-style keys.
AI Studio key vs Vertex AI endpoint mismatch	AIza… keys call generativelanguage.googleapis.com; Vertex uses OAuth/service accounts on a different host. Don't cross them.
Unsupported region	AI Studio keys don't work from every country; check availability or route via a gateway.
Env var plumbing (quotes/whitespace/wrong var name)	print(repr(key)) inside the failing process; re-export cleanly.

Test the key in isolation

One curl against the REST endpoint tells you whether the key itself is fine:

test-gemini-key.sh

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"parts":[{"text":"ping"}]}]}' | head -c 400

Check restrictions and enabled APIs

Cloud Console → APIs & Services → Credentials: open the key. If Application restrictions says "HTTP referrers", server calls will 400 — switch to None or IP-based. Then confirm the Generative Language API is enabled on the same project.

If you need one key for many models anyway

If you're juggling Gemini + Claude + GPT keys, an OpenAI-compatible gateway collapses them into one credential — same code, one base_url, no Google Cloud project required.

If you're calling through Kunavo

Kunavo serves Gemini 2.5 Flash and Pro behind the same OpenAI-compatible endpoint and sk-kunavo key as Claude and GPT — no Google Cloud project, no key restrictions to debug, and it works from regions where AI Studio keys aren't offered. Rates sit well under Google's list price, and the setup is three fields in any OpenAI SDK.

FAQ

My Gemini key works locally but fails in production — why?

Usually referrer/IP restrictions (prod IPs not allowed), a different env file in prod, or the prod project not having the Generative Language API enabled. Diff the key's repr and the project ID between environments.

Is the Gemini API free?

AI Studio has a free tier with strict per-minute quotas; production traffic needs billing enabled (or a gateway). If you're hitting quota errors rather than key errors, see our RESOURCE_EXHAUSTED guide.

More error semantics live in the error reference; getting a key takes a minute via sign up and the authentication docs.