The Complete Guide to Google Gemini API Errors in 2026

Introduction

Google Gemini in 2026 has moved fast. The Gemini 3.x family launched in November 2025 and by mid-2026 spans preview and GA models at every price tier — from Flash-Lite at $0.25 input to 3.1 Pro at $2.00, with a 20x spread that makes model routing more consequential than on any competing platform. The pricing structure itself changed at I/O 2026: pay-as-you-go was replaced by Prepay/Postpay plans, Pro models were removed from the free tier on April 1, and Gemini 2.5 — the family many teams still run in production — shuts down October 16, 2026.

This guide is the definitive reference for the Gemini API as it exists today. It covers the current 3.x lineup, the 2.5 shutdown migration, the thinking tokens that silently inflate output costs, the 200K context threshold that doubles pricing on Pro, the grounding and code-execution tools, and every error surface between them.

Who this guide is for

The guide assumes you have:

• Made real Gemini API requests through AI Studio or Vertex AI
• Read enough of the docs to know what generateContent, tools, and safety_settings mean
• Hit at least one 400 or 429 that you needed to Google

If that describes you, read it end-to-end once to build a mental model of every Gemini concept and gotcha; return to specific chapters when you hit a related error. Each chapter links to the specific error-fix pages that answer narrower questions with tested code.

The four things that changed in 2026

1. Gemini 2.5 shuts down October 16, 2026. Gemini 2.5 Pro, Flash, and Flash-Lite are all scheduled for deprecation. That's roughly two months from this guide's publish date. If your production code still targets gemini-2.5-pro, gemini-2.5-flash, or gemini-2.5-flash-lite, migrate before mid-October or face a hard cutoff. Chapter 6 walks the migration.

2. Pro models are no longer free. On April 1, 2026, Google removed Gemini 3.1 Pro, 3 Pro, and 2.5 Pro from the free API tier. Flash and Flash-Lite remain free with reduced daily quotas. Any test project that relied on free Pro access now returns 403 billing not enabled — enable billing and switch to Prepay or Postpay plans.

3. Billing shifted to Prepay/Postpay plans. On March 23, 2026, Google replaced pay-as-you-go with two named plans: Prepay (advance credit purchase, cheaper effective rate) and Postpay (monthly invoicing, standard rates). Both require billing enabled. Chapter 4 covers the differences.

4. Thinking is now the default and it bills as output. Gemini 3.x models use dynamic thinking by default. The reasoning tokens generated before the visible response bill at the output rate — a prompt that produces 100 visible tokens can bill 3000 tokens when the model thinks hard first. The thinking_level parameter is your only lever; 3.1 Pro has no minimal-thinking mode. Chapter 7 covers the thinking tax in detail.

What's not in this guide

• Consumer Gemini app pricing or features (AI Pro, AI Ultra, Deep Think) — this guide is for the API
• Head-to-head model comparisons across providers — see the Cost Optimization Playbook
• Google Cloud Agent Platform / Vertex AI Agent Builder — a separate product with different error surfaces
• Gemma open models — different distribution model, no API errors to cover

What we do cover: every failure mode of the Gemini API, every migration hazard from 2.5 to 3.x, every configuration trap in the current model lineup, and the cost patterns that actually move production bills.

API architecture at a glance

The Gemini API is exposed two ways: through Google AI Studio (developer-focused, single API key auth) and through Vertex AI (enterprise, service-account auth, GCP-integrated). Both wrap the same underlying models, but with different auth, different feature parity, and different quota structures. This chapter maps the whole surface.

The two-track API

Same underlying models on both. Same request/response shapes. Different auth wrappers and different quota systems. Chapter 11 covers the specific differences you'll hit when migrating between them or running both.

The endpoint map

SDKs

Request lifecycle

1. SDK serialization — Python/TypeScript objects turn into a JSON body
2. Auth — API key (?key= query param or header) for AI Studio; service account bearer token for Vertex
3. Edge routing — request lands on regional endpoint
4. Safety pre-check — prompt evaluated against configured safety_settings; may be blocked before inference
5. Cache lookup — if cached_content referenced, cached prefix loaded
6. Model inference — Gemini generates the response (thinking + text + tool calls)
7. Safety post-check — output evaluated; may be blocked or truncated
8. Response streaming or buffering — SSE or JSON returned
9. Usage accounting — token counts recorded (input, output, thinking, cached, grounding queries)

Errors can fire at any stage. A 401 fires at step 2. A safety block fires at step 4 (prompt) or step 7 (output). A 429 fires at step 3. Understanding which stage failed tells you where to look.

The core object model

• Content — one turn. Has role (user or model) and parts (array).
• Part — typed piece. text, inline_data (base64), file_data (uploaded file ref), function_call, function_response, executable_code, code_execution_result.
• Tool — function_declarations (custom OpenAPI schema), or hosted tools (google_search, code_execution, url_context, computer_use).
• GenerationConfig — temperature, max_output_tokens, thinking_config, response_mime_type, response_schema.
• UsageMetadata — prompt_token_count, candidates_token_count, thoughts_token_count, cached_content_token_count, tool_use_prompt_token_count.

Most errors are shape mismatches on these objects. See the error categories chapter for the full taxonomy.

The 2026 Gemini model lineup

As of August 2026, the callable Gemini lineup spans two generations and eight active models. The 3.x family is the current recommendation — Gemini 3.1 Pro at the top, Gemini 3.5 Flash as the workhorse (and the default across Google's own apps), Gemini 3 Flash and 3.1 Flash-Lite at cost-optimized tiers, plus the newer 3.6/3.7 Flash preview models. The 2.5 family is still available but on a deprecation clock.

Verified from ai.google.dev/gemini-api/docs/pricing as of August 19, 2026. Prices are for standard-context (Pro: <200K input); above the threshold, Pro rates roughly double to $4/$18. All 3.x models use dynamic thinking by default, which bills as output tokens.

What each model is for

• Gemini 3.1 Pro ($2/$12) — flagship reasoning, world knowledge, multimodal work. 2M context. No minimal-thinking mode — every call includes reasoning depth by design. Best for hardest problems where quality justifies the thinking-token overhead.
• Gemini 3.5 Flash ($1.50/$9) — Google's own default across the Gemini app, AI Mode in Search, and Enterprise. Tuned for agentic and coding work. Beats 3.1 Pro on several agentic benchmarks while running several times faster. The right default for most production workloads.
• Gemini 3.7 Flash preview ($1.50/$7.50) — newer than 3.5, cheaper on output, native grounding built in. Use when you want the newest capabilities and can accept preview stability.
• Gemini 3 Flash preview ($0.50/$3) — Pro-grade reasoning at Flash cost. The value pick when 3.5 Flash is more than you need.
• Gemini 3.1 Flash-Lite ($0.25/$1.50) — the high-volume workhorse. Cheapest in the 3.x line, latency-optimized, full thinking-level control. Best for classification, extraction, formatting.
• Deep Think — not a callable API model. Ships only through the Google AI Ultra consumer subscription. If you need extended-reasoning compute via API, Gemini 3.1 Pro with thinking_level: high is the closest equivalent.

Gemini 3.5 Pro — announced but not shipped

Google announced Gemini 3.5 Pro at I/O 2026 but has not shipped it to the API as of August. The current callable flagship is Gemini 3.1 Pro. When 3.5 Pro launches, expect it to sit at or above 3.1 Pro pricing; migration will be straightforward if you're already on 3.x semantics (thinking_level, dynamic thinking defaults).

The 200K threshold on 3.1 Pro

Gemini 3.1 Pro has tiered context pricing at 200K tokens:

A 300K-token workload on 3.1 Pro bills at 2x input and 1.5x output compared to a 150K workload. The 2M context is fully supported — but past 200K, you're paying premium rates for the entire request. Aggressive context trimming pays outsized dividends. Flash models don't have this tiered pricing (yet).

Free tier removal (April 1, 2026)

Before April 1, 2026, Google's Gemini API free tier included all models with daily quotas. After April 1:

• Removed from free tier: Gemini 3.1 Pro, Gemini 3 Pro, Gemini 2.5 Pro (all Pro-tier models)
• Still on free tier: Gemini 3.5 Flash, Gemini 3 Flash, Gemini 3.1 Flash-Lite, Gemini 2.5 Flash, Gemini 2.5 Flash-Lite (with tightened daily quotas)
• Symptom of trying Pro on free tier: 403 billing not enabled. Enable billing on the AI Studio project and select Prepay or Postpay plan.

See 403 billing not enabled for the enable-billing walk-through.

Image generation (billed per image, not per token)

Nano Banana Pro (Gemini 3 Pro Image) and Nano Banana 2 (Gemini 3.1 Flash Image) generate images at per-image pricing that varies by resolution. Not covered in detail here — see Google's image pricing page. Referencing images as input still bills at the standard token rate (documents/images convert to token counts).

Authentication, billing plans & rate limits

Gemini authentication depends on which surface you're on: AI Studio uses a simple API key, Vertex AI uses Google service accounts. Billing changed twice in 2026 — the Prepay/Postpay split replaced pay-as-you-go on March 23, and Pro models moved off the free tier on April 1. Rate limits are tier-based and separate per model family.

The API key (AI Studio)

Get a key from aistudio.google.com → Get API Key. One key per project; keys are scoped to that project's models, quotas, and billing account. Pass the key either as a query parameter or an x-goog-api-key header:

# Query param (SDK default)
POST /v1beta/models/gemini-3.5-flash:generateContent?key=AIza...

# Header (preferred for production)
POST /v1beta/models/gemini-3.5-flash:generateContent
x-goog-api-key: AIza...

Store keys in a secrets manager. The google-genai SDK reads GOOGLE_API_KEY from the environment by default. Never commit keys to source; Google actively scans public GitHub for leaked keys and auto-revokes them.

Service account auth (Vertex AI)

Vertex AI does not accept API keys. You authenticate with a Google Cloud service account and short-lived access tokens:

import google.auth
import google.auth.transport.requests

credentials, project = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)
token = credentials.token

# Then use token as bearer
# Authorization: Bearer {token}

In practice, use the google-cloud-aiplatform or google-genai Vertex mode to handle token refresh automatically. See Vertex service account auth.

Prepay vs Postpay plans (March 23, 2026)

Google replaced pay-as-you-go with two named plans:

Neither plan changes per-token pricing in this guide (published rates apply); Prepay effectively discounts through volume credit packages. Most teams start on Postpay for flexibility, switch to Prepay once volume is predictable.

Rate limit tiers

Google's tier system on AI Studio determines per-model RPM (requests per minute), TPM (tokens per minute), and RPD (requests per day). Tiers unlock automatically with spend.

RPM = requests per minute. TPM = tokens per minute. RPD = requests per day. Exact numbers vary by region and change; verify at ai.google.dev/gemini-api/docs/rate-limits.

Reading rate limit responses

Gemini doesn't return standard x-ratelimit-* headers like OpenAI or Anthropic. Rate limit information is returned only in the 429 error body when you hit the limit:

{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED",
    "details": [{
      "@type": "type.googleapis.com/google.rpc.QuotaFailure",
      "violations": [{
        "quotaMetric": "generativelanguage.googleapis.com/generate_content_requests",
        "quotaId": "GenerateRequestsPerMinutePerProjectPerModel",
        "quotaValue": "1000"
      }]
    }, {
      "@type": "type.googleapis.com/google.rpc.RetryInfo",
      "retryDelay": "45s"
    }]
  }
}

Parse details[?type=RetryInfo].retryDelay and sleep for that duration before retrying. Without proactive rate limit headers, you're limited to reactive backoff — instrument at the client level. See 429 rate limit tier quota.

Common auth errors

• 401 API_KEY_INVALID — key wrong, revoked, or not activated. See 401 invalid API key
• 403 billing not enabled — trying to use a paid model (Pro) on a project without billing after April 1, 2026. See 403 billing not enabled
• 429 RESOURCE_EXHAUSTED — RPM, TPM, or RPD hit. See 429 tier quota
• 500 INTERNAL — retry with backoff. See 500 retry strategy

Every Gemini error category

Everything that can go wrong with a Gemini API request falls into one of ten categories. This chapter maps each category, describes the failure mode, and links to the specific error-fix pages.

1. Authentication & billing errors (401, 403)

Fires at: Request auth stage.
Common causes: Invalid or revoked API key, service account misconfiguration on Vertex, Pro model called on a project without billing (post-April-1), quota exhausted at the billing account level.

Auth errors are almost never in your request shape. The 403 billing not enabled error is new in 2026 — teams that built on the free Pro tier before April 1 must enable billing and choose a plan (Prepay or Postpay) before Pro models will respond.

Related error pages: 401 invalid API key · 403 billing not enabled · Vertex service account auth

2. Rate limit errors (429)

Fires at: Quota enforcement, before inference.
Common causes: RPM cap, TPM cap, RPD cap (Google's daily quota is stricter than most providers), tier lockout during high-tier upgrade window.

Gemini's per-day quota is often the first cap you hit — it's much lower than OpenAI or Anthropic per-day equivalents. High-burst workloads can trip RPM easily; long-context prompts trip TPM. Parse the retryDelay from the error body and back off.

Related error pages: 429 tier quota

3. Request shape errors (400)

Fires at: Request validation.
Common causes: Invalid role in contents array (must be user or model), malformed parts, unsupported MIME type in inline_data, invalid model ID for the endpoint.

Gemini uses user and model roles (not assistant). The contents array must alternate user and model; two user turns in a row throw 400. See context length for token overflow.

4. Gemini 2.5 deprecation errors (post-Oct 16, 2026)

Fires at: Any request to gemini-2.5-pro, gemini-2.5-flash, or gemini-2.5-flash-lite after October 16, 2026.
Common causes: Code not migrated to 3.x before the deadline.

From October 16 onward, 2.5 model IDs return 404 model_not_found. Chapter 6 walks the full migration; if you're reading this before mid-October and your production still targets 2.5, migrate now.

Related error pages: Gemini 2.5 shutdown

5. Context length errors (400)

Fires at: Token validation, before inference.
Common causes: Input + max_output_tokens exceeds model context; crossing the 200K threshold on 3.1 Pro silently doubles cost (not an error, but silently expensive).

Pro models support 2M context; Flash and Flash-Lite support 1M. The 200K threshold on 3.1 Pro is a billing tier boundary, not a hard cap — but it doubles input cost for the entire request. Measure with countTokens before assuming your prompt is in standard tier.

Related error pages: context_length_exceeded · 200K pricing threshold

6. Thinking token surprises

Fires at: Usage accounting (not an error — a cost surprise).
Common causes: Dynamic thinking is on by default in 3.x; thinking tokens bill as output; 3.1 Pro has no minimal-thinking mode.

Gemini 3.x models think by default. A prompt producing 100 visible response tokens can generate 3000 thinking tokens — all billed at the output rate. Chapter 7 covers control via thinking_config.thinking_level.

Related error pages: Thinking tokens billed as output · thinking_level parameter

7. Function calling errors

Fires at: Tool schema validation or the tool loop.
Common causes: Invalid OpenAPI schema in function_declarations, wrong tool_config.function_calling_config.mode, function response not matching declared return type.

Gemini uses OpenAPI Schema (subset of JSON Schema) for function declarations. Common mistakes: using $ref (not supported), using JSON Schema-specific keywords like additionalProperties, or passing enum without type.

Related error pages: Invalid schema · tool_config mode

8. Safety block errors

Fires at: Safety pre-check (prompt) or post-check (output).
Common causes: Content triggers safety threshold; safety_settings not tuned for use case; prompt or response contains policy-adjacent content.

A blocked response is not an HTTP error — the response returns 200 with finish_reason: SAFETY and empty content. A blocked prompt returns prompt_feedback.block_reason. Tune safety_settings with block_threshold per harm category; the default is BLOCK_MEDIUM_AND_ABOVE.

Related error pages: safety_settings threshold · finish_reason=SAFETY · prompt block_reason

9. Grounding & code execution errors

Fires at: During tool execution.
Common causes: Grounding with Search returns no valid sources; code_execution sandbox timeout; dynamic retrieval threshold misconfigured; grounding billing surprise (per-1K queries).

Grounding with Search is priced separately at $14/1K queries (3.x) or $35/1K (2.x), on top of standard token billing. Dynamic retrieval mode only bills queries that actually surface grounding sources — set the threshold appropriately.

Related error pages: Grounding billing · code_execution sandbox

10. Service-side errors (5xx)

Fires at: Google infrastructure.
Common causes: Internal error (500), gateway timeout (504), preview model temporarily unavailable.

Preview models (3.7 Flash, 3 Flash, 3.1 Pro Preview) hit 5xx more often than GA. Retry with exponential backoff plus jitter. See 500 retry strategy.

Gemini 2.5 shutdown (October 16, 2026)

On October 16, 2026, Google shuts down Gemini 2.5 Pro, Gemini 2.5 Flash, and Gemini 2.5 Flash-Lite. Any code still targeting those model IDs returns 404 after the deadline. That's roughly two months from this guide's publish date. This chapter is the migration playbook.

What breaks on October 16

• gemini-2.5-pro — 404 model_not_found
• gemini-2.5-flash — 404 model_not_found
• gemini-2.5-flash-lite — 404 model_not_found
• Any legacy 2.5 model IDs with date suffixes (e.g., gemini-2.5-pro-002) — same fate

The migration map

Every path is a price increase in raw per-token terms. The offsetting factors: 3.x quality is measurably better, so lower effort levels often produce equal or better results at lower total token counts; grounding is native in 3.x (no separate billing chain); and dynamic thinking often improves output quality without you needing to prompt-engineer for it.

The 6-step migration

Step 1: Inventory 2.5 usage

rg "gemini-2\.5" --glob "*.py" --glob "*.ts" --glob "*.go"
rg "gemini-2-5" --glob "*.py" --glob "*.ts" --glob "*.go"

# Also check config files
rg "gemini-2\.5" --glob "*.yaml" --glob "*.json" --glob "*.env"

Every match is a migration target. Include model ID constants, config files, tests, and prompt templates.

Step 2: Add a routing wrapper

Route all Gemini calls through a single helper. This lets you flip model IDs without touching every call site:

MODEL_MIGRATION_MAP = {
    "gemini-2.5-pro":         "gemini-3.1-pro-preview",
    "gemini-2.5-flash":       "gemini-3.5-flash",
    "gemini-2.5-flash-lite":  "gemini-3.1-flash-lite",
}

def call_gemini(model_id: str, **kwargs):
    # Auto-migrate 2.5 IDs to 3.x replacements
    if model_id in MODEL_MIGRATION_MAP:
        old = model_id
        model_id = MODEL_MIGRATION_MAP[model_id]
        log.warning("Migrated %s -> %s", old, model_id)

    return client.models.generate_content(
        model=model_id,
        **kwargs,
    )

Step 3: Add thinking_config defaults

3.x models default to dynamic thinking, which bills as output. Set thinking_level explicitly per workload to control cost:

THINKING_LEVEL_BY_TASK = {
    "classify":       "low",
    "extract":        "low",
    "summarize":      "low",
    "chat":           "medium",
    "review_code":    "high",
    "complex_reason": "high",
}

def call_gemini(model_id, task_type, **kwargs):
    config = kwargs.get("config", {})
    config["thinking_config"] = {
        "thinking_level": THINKING_LEVEL_BY_TASK.get(task_type, "medium"),
        "include_thoughts": False,   # don't return thinking to save bandwidth
    }
    return client.models.generate_content(
        model=MODEL_MIGRATION_MAP.get(model_id, model_id),
        config=config,
        **kwargs,
    )

Step 4: Re-measure cost on a representative corpus

Run 50-100 representative prompts through both 2.5 and 3.x, tracking input tokens, output tokens (including thinking), and cost. Expect input to roughly match, output to grow with thinking — sometimes 2-4x. Adjust thinking_level and max_output_tokens to control.

Step 5: Re-validate safety_settings

Safety thresholds behave slightly differently between 2.5 and 3.x. A prompt that passed 2.5 with BLOCK_MEDIUM_AND_ABOVE may block on 3.x, or vice versa. Run your safety-sensitive corpus through both and adjust thresholds.

Step 6: Golden-set regression test

Before flipping production traffic, run 50-100 representative user prompts through both stacks. Compare on quality, latency, and cost. Flip production only after the golden set confirms quality holds and cost is within your acceptable delta.

Migration cost example

Workload: 500K requests/month, avg 1500 input + 400 output tokens per request, currently on Gemini 2.5 Flash:

Three viable paths: 3.5 Flash for quality lift at ~4x cost, 3 Flash for balanced upgrade, Flash-Lite for cost reduction. Route by task complexity — not everything needs to move to the same tier.

Thinking config & the reasoning tax

Gemini 3.x models use dynamic thinking by default. Before producing the visible response, the model generates reasoning tokens — and every one of them bills as an output token. On complex prompts, thinking tokens can dominate the response cost. This chapter covers what thinking is, how to control it, and the trap of leaving 3.1 Pro on defaults.

What thinking is

Thinking (a.k.a. reasoning) is the model's internal chain-of-thought before the visible response. On Gemini 2.5, thinking was opt-in via thinking.budget_tokens. On Gemini 3.x, it's on by default with dynamic depth — the model decides per prompt how much to think.

A simple factual prompt might generate 20 thinking tokens. A hard reasoning prompt might generate 3000. Both bill at the output rate. On Gemini 3.1 Pro ($12/M output), 3000 thinking tokens = $0.036 per request just for reasoning.

The thinking_level parameter (3.x)

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain the CAP theorem.",
    config={
        "thinking_config": {
            "thinking_level": "low",        # low | medium | high
            "include_thoughts": False,      # False keeps thinking out of response
        },
    },
)
print(response.text)
print("Thoughts tokens:", response.usage_metadata.thoughts_token_count)

See thinking_level parameter for the full workload map.

Gemini 3.1 Pro has no minimal-thinking mode

Setting thinking_level: low on Gemini 3.1 Pro doesn't fully disable thinking — the model always thinks meaningfully. That's a design choice: 3.1 Pro is positioned for hard reasoning; low-effort work should route to Flash. See 3.1 Pro no minimal thinking.

Practical implication: routing simple classification to 3.1 Pro is doubly expensive — you pay Pro rates AND unavoidable thinking overhead. Route classification to Flash-Lite; save Pro for prompts where deep thinking is worth $12/M output.

Measuring thinking cost

u = response.usage_metadata
print(f"prompt tokens:        {u.prompt_token_count}")
print(f"response tokens:      {u.candidates_token_count}")
print(f"thinking tokens:      {u.thoughts_token_count or 0}")
print(f"cached tokens:        {u.cached_content_token_count or 0}")
print(f"tool tokens:          {u.tool_use_prompt_token_count or 0}")

# Cost for Gemini 3.5 Flash
def request_cost(usage):
    input_rate = 1.50 / 1_000_000
    output_rate = 9.00 / 1_000_000

    prompt = usage.prompt_token_count
    output = usage.candidates_token_count
    thoughts = usage.thoughts_token_count or 0

    # Thinking bills at output rate
    return (prompt * input_rate) + ((output + thoughts) * output_rate)

Track thoughts_token_count per workflow. If thinking regularly exceeds 2x the visible output, lower thinking_level or route to a smaller model.

Should you include_thoughts?

Default is include_thoughts: False — thinking tokens are generated (and billed) but not returned in the response. Setting True returns them in response.candidates[0].content.parts with thought=True. Only worth it if you're building a UI that shows the reasoning or debugging why the model produced a particular output.

Legacy: thinking.budget_tokens (Gemini 2.5)

On Gemini 2.5, thinking was controlled by thinking.budget_tokens:

# Gemini 2.5 legacy pattern (works until Oct 16, 2026)
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="...",
    config={
        "thinking_config": {
            "thinking_budget": 2000,   # max tokens for thinking
        },
    },
)

On 3.x, budget-based control is gone — thinking_level is the only lever. Migration means converting numeric budgets to enum levels; approximate: 0-500 → low, 500-2000 → medium, 2000+ → high. See thinking_budget legacy.

Function calling, grounding & tools

Gemini exposes three tool families: custom function declarations (OpenAPI schema you define), Google-hosted tools (google_search, code_execution, url_context, computer_use), and structured output via response_schema. Each has distinct configuration, distinct failure modes, and distinct billing.

Function declarations (custom tools)

Define functions using OpenAPI Schema (a subset of JSON Schema):

tools = [{
    "function_declarations": [{
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
            "type": "OBJECT",
            "properties": {
                "location": {"type": "STRING"},
                "unit": {"type": "STRING", "enum": ["celsius", "fahrenheit"]},
            },
            "required": ["location"],
        },
    }],
}]

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What's the weather in Paris?",
    config={"tools": tools},
)

# Iterate function calls
for part in response.candidates[0].content.parts:
    if part.function_call:
        name = part.function_call.name
        args = dict(part.function_call.args)
        result = execute(name, args)
        # Send result back
        followup = client.models.generate_content(
            model="gemini-3.5-flash",
            contents=[
                {"role": "user", "parts": [{"text": "What's the weather in Paris?"}]},
                {"role": "model", "parts": [{"function_call": part.function_call}]},
                {"role": "user", "parts": [{"function_response": {
                    "name": name,
                    "response": {"result": result},
                }}]},
            ],
            config={"tools": tools},
        )

Schema gotchas

Gemini's OpenAPI subset differs from JSON Schema in specific ways:

• Types are UPPERCASE (OBJECT, STRING, INTEGER), not lowercase
• No $ref — inline all schemas
• No additionalProperties
• No allOf, oneOf, anyOf, not
• Limited format support (e.g., date-time, enum)

See invalid OpenAPI schema for the common conversion errors.

tool_config: forcing tool use

config={
    "tools": tools,
    "tool_config": {
        "function_calling_config": {
            "mode": "ANY",   # ANY | AUTO | NONE
            "allowed_function_names": ["get_weather"],   # optional filter
        },
    },
}

• AUTO (default) — model decides whether to call a function
• ANY — model must call some function (optionally from allowed list)
• NONE — model may not call functions

See tool_config mode.

Parallel function calls

Gemini can return multiple function_call parts in a single response. Iterate all parts, execute them (parallel where safe), send all function_response results back in a single follow-up turn. See parallel function calls.

Grounding with Google Search

Grounding sources responses in real-time web results. Native on Gemini 3.x:

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What are the latest earnings for Google?",
    config={
        "tools": [{"google_search": {}}],
    },
)

# Response includes grounding metadata
gmeta = response.candidates[0].grounding_metadata
for source in gmeta.grounding_chunks:
    print(f"Source: {source.web.uri}")

Grounding bills separately: $14 per 1K queries on 3.x models, $35 per 1K on 2.x. The 3.x family gets 5,000 free grounding queries per month (shared across the account). See grounding billing.

Dynamic retrieval mode

On 2.x, Grounding had a dynamic_retrieval_config where you could set a threshold — only prompts that scored above the threshold would trigger a grounded search, saving cost:

# Gemini 2.x pattern
config={
    "tools": [{
        "google_search_retrieval": {
            "dynamic_retrieval_config": {
                "mode": "MODE_DYNAMIC",
                "dynamic_threshold": 0.7,   # only ground if score > 0.7
            },
        },
    }],
}

On 3.x, the equivalent is Google-managed under the hood — no user-facing threshold. Only requests where the grounding actually surfaces sources are billed. See dynamic retrieval.

Code execution tool

The code_execution tool gives Gemini a Python sandbox. The model can write and execute Python to solve problems requiring computation:

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="What's the 47th Fibonacci number?",
    config={"tools": [{"code_execution": {}}]},
)

# Response contains executable_code and code_execution_result parts
for part in response.candidates[0].content.parts:
    if part.executable_code:
        print("Code:", part.executable_code.code)
    elif part.code_execution_result:
        print("Result:", part.code_execution_result.output)
    elif part.text:
        print("Text:", part.text)

Sandbox is per-call, isolated, ~30-second timeout, restricted network access. See code_execution sandbox errors.

Structured output via response_schema

Force JSON output matching a schema:

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Extract: Ada Lovelace, born 1815, mathematician",
    config={
        "response_mime_type": "application/json",
        "response_schema": {
            "type": "OBJECT",
            "properties": {
                "name": {"type": "STRING"},
                "birth_year": {"type": "INTEGER"},
                "profession": {"type": "STRING"},
            },
            "required": ["name", "birth_year", "profession"],
        },
    },
)

import json
data = json.loads(response.text)

Same OpenAPI subset rules as function declarations — uppercase types, no $ref, no advanced JSON Schema features. On 3.x, structured output is enforced strictly; on 2.x it was best-effort.

Context caching & long-context pricing

Gemini has two caching mechanisms — implicit caching (automatic, 90% discount on cache reads) and explicit caching (opt-in via cachedContents, more control). Combined with the 200K threshold on Gemini 3.1 Pro that doubles pricing for the entire request, caching is the biggest cost lever on Gemini in 2026.

Implicit caching (automatic)

When the same prompt prefix appears across multiple requests within the cache lifetime, Google automatically caches the prefix. Subsequent requests hitting the same prefix bill the cached portion at 10% of the standard input rate — a 90% discount, no configuration required.

# Same system prompt across many requests → automatic cache
system_prompt = "You are a customer support agent for Acme Corp..."   # ~2000 tokens

for question in user_questions:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=[
            {"role": "user", "parts": [{"text": system_prompt}]},
            {"role": "user", "parts": [{"text": question}]},
        ],
    )
    print("cached tokens:", response.usage_metadata.cached_content_token_count)

Explicit caching via cachedContents

For workloads where you want guaranteed caching (long documents, RAG contexts), create a cached content explicitly:

# 1. Create the cache (persists 5 min default, 1 hour max)
cached = client.caches.create(
    model="gemini-3.5-flash",
    contents=[{"role": "user", "parts": [{"text": LONG_DOCUMENT}]}],
    ttl="3600s",   # 1 hour
    system_instruction="You are analyzing this document.",
)

# 2. Reference in subsequent requests
for question in questions_about_document:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=question,
        config={"cached_content": cached.name},
    )

Cache pricing

Explicit cache pricing includes a storage cost per hour on top of read savings. Break-even math depends on hit rate — see below.

Break-even math

For a 100K-token cached document on Gemini 3.5 Flash:

• Storage cost: $0.10/hour (100K tokens × $1.00/1M/hr)
• Savings per cache read: 100K tokens × ($1.50 − $0.15) / 1M = $0.135 per read
• Break-even: 1 cache read per hour recovers storage

Any workload where the same document is queried more than once per hour benefits from explicit caching. Below that frequency, rely on implicit caching (no storage cost) or skip caching.

The 200K threshold on Gemini 3.1 Pro

Gemini 3.1 Pro is the only model in the current lineup with tiered context pricing. Below 200K input tokens, standard rates apply. At and above 200K, rates roughly double for the entire request:

Implications:

1. A workload consistently at 300K tokens costs roughly 2x a workload at 150K on 3.1 Pro. Aggressive context trimming pays outsized dividends.
2. Cache reads still get their 90% discount, but at the doubled rate — cached 300K prompt reads at $0.40/1M instead of $0.20/1M.
3. Flash and Flash-Lite don't have this tiered pricing. If your workload is chronically long-context, Flash tiers offer more predictable billing.

See 200K threshold for measurement patterns.

The 2M context window on Pro

Gemini 3.1 Pro and Gemini 2.5 Pro support 2M-token context — the largest of any frontier model. The catch: past the 200K threshold, you're paying premium rates. In practice, workloads that regularly exceed 200K should compare 3.1 Pro (2M capable, premium above 200K) against 3.5 Flash (1M capable, flat pricing) and 3 Flash preview ($0.50/$3, 1M capable, cheapest 3.x flat).

See 2M context practical limits for RAG chunking patterns that avoid the threshold.

Pricing & cost optimization

Gemini's pricing lineup in 2026 spans a 20x range from Flash-Lite ($0.25 input) to Pro ($2 input, $4 above 200K). Combined with automatic caching, batch discounts, thinking token overhead, and separate grounding billing, cost optimization has more levers on Gemini than on any other frontier API.

2026 rates (per million tokens, verified August 19)

Verified from ai.google.dev/gemini-api/docs/pricing on August 19, 2026. Cached input is 10% of standard input; explicit caching adds storage cost per hour. Batch is 50% of standard. Above 200K on 3.1 Pro roughly doubles rates. Thinking tokens bill at the output rate (3.x default is on).

Grounding pricing (separate)

Grounding bills on top of standard token costs. Only requests where grounding actually surfaces sources are billed. A 50-request/day grounded chat workflow → 1500/month → $21/month in grounding (after free tier).

The five biggest cost levers

Ordered by typical impact:

1. Model routing (20x spread available) — Gemini's price spread is the largest of any frontier API. Route by task complexity: Flash-Lite for classification, Flash for most work, Pro only for hardest reasoning. Routing simple classification to Pro is a ~40x overpay when you include thinking overhead.
2. Thinking level tuning — 3.x defaults to dynamic thinking, which bills as output. Setting thinking_level: low on Flash workloads can 3-5x reduce total output tokens.
3. Automatic caching (90% off cache reads) — same system prompt across requests caches automatically. Verify with usage_metadata.cached_content_token_count.
4. Stay under 200K on 3.1 Pro — crossing the threshold roughly 2x's your bill. Aggressive RAG chunking beats sending the whole corpus.
5. Batch API (50% off both input and output) — for non-realtime work. Overnight reports, offline classification, backfill jobs.

Real workload cost examples

For 1M requests/month at 2000 input + 500 output tokens each:

Simplified example — actual savings depend on cache hit rate, thinking token generation, routing accuracy. Directional.

Cost anti-patterns to fix

• Defaulting to Gemini 3.1 Pro for everything — thinking overhead + Pro rates make it 10-40x more expensive than Flash-Lite for tasks Flash-Lite handles well
• Leaving thinking_level at default across all workloads — classification and extraction almost never need medium/high thinking
• Injecting timestamps or per-user data into the system prompt — destroys implicit caching
• Running background reports through synchronous calls instead of Batch — leaving 50% on the table
• Ignoring the 200K threshold on 3.1 Pro — silent 2x cost surprises
• Not tracking thoughts_token_count — thinking cost can dominate the bill invisibly
• Using grounding without measuring queries/month — the $14/1K adds up fast on chat workloads

For cross-provider cost patterns (Gemini vs OpenAI vs Claude), see the AI API Cost Optimization Playbook 2026.

Live API, Vertex AI & multimodal

Three surfaces that behave differently from standard generateContent: the Live API for bidirectional streaming (WebSocket, voice), Vertex AI as the enterprise deployment target with different auth and quotas, and Gemini's native multimodal capabilities (image, video, audio, PDF as inputs). Each has distinct error surfaces.

Live API — WebSocket for bidirectional streaming

The Live API supports real-time bidirectional audio + text streaming. Used for voice assistants, live transcription, interactive agents:

from google import genai
import asyncio

client = genai.Client()

async def live_session():
    async with client.aio.live.connect(
        model="gemini-3.5-flash-live-preview",
        config={
            "response_modalities": ["AUDIO"],   # or ["TEXT"] or both
            "system_instruction": "You are a helpful voice assistant.",
            "input_audio_transcription": {},
            "output_audio_transcription": {},
        },
    ) as session:
        # Send text
        await session.send(input="Hello, what can you help me with?", end_of_turn=True)

        # Or send audio chunks
        # await session.send(input={"data": audio_bytes, "mime_type": "audio/pcm"})

        # Receive stream
        async for message in session.receive():
            if message.data:
                # Base64-decoded PCM16 audio
                play_audio(message.data)
            if message.text:
                print(message.text, end="")

asyncio.run(live_session())

Live API failure modes: WebSocket connection drops, audio format mismatch, session config validation. See connection drop, audio format, modalities config.

Native multimodal inputs

Gemini accepts images, video, audio, and PDFs as inputs — no separate endpoint. Two ways to attach:

# Inline (base64, small files)
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        {"role": "user", "parts": [
            {"text": "Describe this image:"},
            {"inline_data": {
                "mime_type": "image/jpeg",
                "data": base64_encoded_image,
            }},
        ]},
    ],
)

# File API (larger files, persists 48 hours)
uploaded = client.files.upload(file="video.mp4")

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=[
        {"role": "user", "parts": [
            {"text": "Summarize this video:"},
            {"file_data": {
                "file_uri": uploaded.uri,
                "mime_type": "video/mp4",
            }},
        ]},
    ],
)

Multimodal token counts

Non-text inputs convert to token counts for billing:

A 60-second video on Flash: ~18,000 tokens = ~$0.027 input on 3.5 Flash. A 30-page PDF on Flash: ~7,740 tokens. Video and long PDFs are the biggest multimodal cost surprise — measure with countTokens.

Vertex AI vs AI Studio

Same underlying models. Different auth, different quotas, different feature parity, different data residency guarantees.

See Vertex AI vs AI Studio for the full migration guide.

Vertex-specific gotchas

• Model ID pattern differs — Vertex uses publishers/google/models/gemini-3.5-flash, not the bare model ID
• Region matters — some models only available in specific regions (us-central1 has the best coverage)
• Preview models lag — Gemini 3.1 Pro preview may not be on Vertex when it's on AI Studio
• Auth token refresh — service account tokens expire hourly; SDKs handle refresh automatically, custom HTTP clients don't
• Global endpoints for lower latency — some models have global endpoints; check availability per model

See Vertex AI region availability.

Production checklist

Twenty items to verify before your Gemini integration goes to production. Each corresponds to at least one outage or cost incident from real 2026 deployments — with special attention to the October 16 Gemini 2.5 shutdown and the thinking-token cost trap.

Auth & billing

1. API key (AI Studio) or service account (Vertex) stored in a secrets manager
2. Billing enabled and plan selected (Prepay or Postpay) — required for Pro models after April 1, 2026
3. Separate keys/projects per environment (dev, staging, prod)
4. Billing alerts configured at 50%, 75%, 100% of expected monthly spend

Gemini 2.5 migration (deadline: October 16, 2026)

5. Zero calls to gemini-2.5-pro, gemini-2.5-flash, or gemini-2.5-flash-lite
6. Model routing wrapper deployed with 2.5 → 3.x mapping
7. Golden set validated on 3.x replacements before flipping production

Rate limits & retries

8. Exponential backoff with jitter for 429 and 5xx (cap 3-5 retries)
9. Parse retryDelay from 429 error body when present
10. Daily quota (RPD) monitored separately from RPM/TPM — Gemini's daily caps are stricter
11. Circuit breaker for sustained 5xx or 429

Cost control

12. thinking_level explicitly set per workload — not defaults
13. Classification/extraction routed to Flash-Lite, not Flash or Pro
14. Long-context workloads measured against 200K threshold on 3.1 Pro; reduced or accepted 2x billing knowingly
15. Cache hit rate measured via usage_metadata.cached_content_token_count; alert if below 40% on multi-turn workloads
16. Non-realtime workloads submitted to Batch API for 50% discount
17. Grounding query count tracked separately — bills at $14/$35 per 1K on top of tokens

Error handling & observability

18. Safety blocks detected — check finish_reason=SAFETY and prompt_feedback.block_reason on every response
19. thoughts_token_count logged for every request; alert on cost outliers
20. Response IDs logged for every request (used in Google support cases)

Frequently asked questions

The full library — 32 Gemini error pages

Every Gemini error-fix page on AI Error Hub, organized by category. Bookmark this section — when you hit a specific error, jump straight to the page that walks through it with tested code.