Gemini API Setup and Error Reference
A compact reference for Gemini API setup, API keys, generateContent, common errors, rate-limit dimensions, safety blocks, key leakage and debugging checks.
| Item | Value | Debug check |
|---|---|---|
| Base URL | https://generativelanguage.googleapis.com | Gemini Developer API REST calls use the Google Generative Language API host. |
| Generate content | POST /v1beta/models/{model}:generateContent | Common entry for text, image and multi-turn generation. |
| Model name | gemini-3.5-flash etc. | Model names change quickly; confirm from official model pages or SDK examples. |
| Authentication | x-goog-api-key or SDK api_key | For 403/permission issues, check key, project, permissions and API restrictions. |
| Google Cloud project | project-bound key | Each Gemini API key is associated with a Google Cloud project for billing and permissions. |
| Environment variable | GEMINI_API_KEY | Use env vars locally and in deployment; do not ship keys in frontend code. |
| Security restrictions | API restrictions | Keys used only for Gemini should be restricted to the Gemini API. |
| Output result | finishReason / safety | If no text is returned, inspect finishReason, safety blocks and candidates. |
| HTTP | Status / scenario | Meaning | Check first |
|---|---|---|---|
400 | INVALID_ARGUMENT | Invalid request parameter, model name or content shape. | Check model, contents, parts, role, JSON shape and generation config. |
401 | UNAUTHENTICATED | Missing or invalid authentication. | Check x-goog-api-key, environment variable and whether the service is enabled. |
403 | PERMISSION_DENIED | Key lacks permission, project is wrong, or tuned model auth is wrong. | Check project permissions, API restrictions, IAM and tuned model access path. |
404 | NOT_FOUND | Model, resource or endpoint not found. | Check model name, API version, region and resource ID. |
429 | RESOURCE_EXHAUSTED | RPM, TPM or RPD limit exceeded. | Lower concurrency, retry with backoff and inspect current tier limits. |
500 | INTERNAL | Server-side error. | Log request context and retry with backoff. |
503 | UNAVAILABLE | Temporary service unavailability or model overload. | Retry with backoff; optionally switch model or delay work. |
finishReason | SAFETY / MAX_TOKENS | Response did not produce normal text. | Inspect safety ratings, max output tokens and prompt content. |
| Dimension | Form | Notes |
|---|---|---|
| RPM | requests / minute | Request-count dimension; exceeding any dimension triggers rate limit errors. |
| TPM | input tokens / minute | Input-token dimension; long context hits it faster. |
| RPD | requests / day | Daily request dimension, common on free or low-tier projects. |
| Project | Google Cloud project | Key, billing, permissions and API restrictions are project-bound. |
| Blocked key | leaked key | Keys reported as leaked may be blocked; generate a new key and update deployments. |
- Common community issues cluster around 403, 429, project-bound keys, frontend exposure, blocked keys, finishReason safety, no-text responses and model/API-version mismatches.
- Gemini API keys are bound to Google Cloud projects; permissions, billing, collaborators and API restrictions all need project-level checks.
- 403 PERMISSION_DENIED often means wrong key, wrong project, mismatched API restrictions or tuned-model authentication issues.
- 429 can be triggered by RPM, TPM or RPD; reducing concurrency and long context both can help.
- If no text is returned, inspect finishReason, candidates, safety ratings and max output tokens.
- Do not treat Gemini API keys as harmless frontend config. Browser, mobile and public-repo exposure can create billing and quota risk.
- Keys suspected of leakage may be blocked by Google; generate a new key and update deployments.
Source: official Google AI for Developers Gemini API documentation, API key guide, troubleshooting guide, rate-limit documentation and recurring community troubleshooting topics. Community posts are used as topic signals only; official docs and console limits remain authoritative.
This Gemini API setup and error-code reference helps debug Gemini API keys, 403 PERMISSION_DENIED, 429 RESOURCE_EXHAUSTED, blocked keys, generateContent failures, finishReason safety, no-text responses, frontend key exposure and rate-limit issues.
Related search intents: Gemini API setup · Gemini API key · Gemini API 403 · Gemini API 429 · RESOURCE_EXHAUSTED · PERMISSION_DENIED · generateContent · finishReason · safety block · Gemini rate limit · Gemini API key leaked · Gemini blocked key · Gemini no text response · Google AI Studio key
FAQ
How do Gemini API REST calls authenticate?
A common REST pattern is the x-goog-api-key header; official SDKs can pass api_key at client initialization. Use environment variables in production and confirm the key belongs to the right Google Cloud project.
How do I debug 403 PERMISSION_DENIED?
Confirm the key belongs to the right Google Cloud project, then check IAM, API restrictions, Generative Language API enablement, billing status and whether you are accessing a tuned model.
What is 429 RESOURCE_EXHAUSTED?
It means a rate-limit dimension such as RPM, TPM or RPD was exceeded. Lower concurrency, reduce context length, retry with backoff or inspect your current tier limits.
Why did Gemini return no text?
The response may have a safety, MAX_TOKENS, RECITATION or candidate-structure issue. Inspect finishReason, safety ratings, candidates and max output tokens; do not rely only on response.text.
What should I do if a key is blocked?
If a key is suspected of leakage or is marked blocked, generate a replacement key in Google AI Studio or Cloud Console, update deployments, disable the old key and inspect recent usage/billing.
Can I put a Gemini API key directly in frontend code?
Not recommended. Even with API restrictions, browser, mobile and public-repository exposure can create billing, quota and abuse risk. Production apps should use a backend proxy or server-side authorization layer.
Why is there still risk after HTTP referrer restrictions?
Referrer, package-name or IP restrictions reduce misuse but do not replace server-side authorization. Recent community incidents cluster around frontend/mobile keys being reused, quotas drained and unexpected bills.
Why do I get model not found or 404?
Common causes are stale model names, API-version mismatch, unsupported region/project access, or mixing Vertex AI and Gemini Developer API model paths.
Why are free-tier and paid-tier limits different?
Gemini limits vary by project, model and tier. Do not treat example-code models or limits as production guarantees; verify the current rate-limits page and console before launch.
How do I tell prompt issues from safety blocks?
Inspect finishReason and safety ratings first. If the finish reason is safety- or recitation-related, increasing max tokens will not fix it; adjust input, system instructions, output requirements or fallback handling.