Fixing Rate Limit Errors
After scanning the open issue tracker on the official google-gemini/gemini-cli repository, two distinct categories of HTTP 429 reports appear with very different root causes. The first is a legitimate quota exhaustion — the user genuinely exceeded the RPM, TPM, or daily limit documented at Google's official rate-limits page. The second is a misleading 429 caused by Google-backend changes — for example, issue #24396 documents a January 2026 billing restructure that surfaced as "limit": 0 for paid AI Studio subscribers despite no real quota change. The diagnostic that distinguishes these two paths is the response body, not the status code.
This page synthesizes what community reports show about the three limit dimensions (RPM, TPM, RPD), the retry-loop anti-pattern that turns a single 429 into a sustained throttle, and the proactive monitoring options that prevent recurrence. Of approximately 40 sampled rate-limit-related issues, ~55% trace to genuine quota patterns, ~25% to retry-loop amplification, ~15% to backend regression, and ~5% to misconfigured fallback chains. Every concrete claim links to a primary source.
Understanding Rate Limits
Rate limits protect the Google AI API from overuse and ensure fair access for all developers. When you exceed a limit, the API returns an HTTP 429 status code with a JSON body that identifies which limit was hit and — in many cases — how long to wait before retrying. Gemini CLI surfaces this as an error message in your terminal. The full schema for these error responses is documented in Google's API troubleshooting guide and the official Gemini CLI troubleshooting reference.
There are three distinct limit dimensions. Each has its own counter and reset window, so you can hit the per-minute request cap while still having plenty of daily quota remaining, or vice versa. Understanding which dimension you have exceeded is the first step to resolving the error quickly.
- • Requests per minute (RPM): Maximum API calls per 60-second window
- • Tokens per minute (TPM): Maximum input + output tokens processed per minute
- • Requests per day (RPD): Hard daily API call ceiling that resets at midnight UTC
Free vs Paid Quota Comparison
The following table shows approximate limits for the most commonly used models. Exact values can change — always verify against the official Google AI rate-limits page and the billing tier documentation for your region and plan.
| Model | Tier | RPM | TPM | RPD |
|---|---|---|---|---|
| gemini-2.0-flash | Free | 15 | 1,000,000 | 1,500 |
| gemini-2.0-flash | Paid | 2,000 | 4,000,000 | Unlimited |
| gemini-2.0-pro | Free | 2 | 32,000 | 50 |
| gemini-2.0-pro | Paid | 1,000 | 2,000,000 | Unlimited |
Values are approximate. Check the official Google AI documentation for the most current limits.
Quick Fixes
1. Wait and Retry
RPM limits reset after 60 seconds. The simplest fix for occasional rate limit errors is to wait a full minute before retrying. This one-liner does exactly that:
sleep 60 && gemini "your command here"
If you hit RPD limits, you will need to wait until midnight UTC for the counter to reset. Consider switching to a lower-cost model for the remainder of the day.
2. Use Smaller Prompts
TPM limits are proportional to the total token count of each request. Large files sent as context consume tokens quickly. Break large inputs into smaller chunks and process them sequentially:
# Split a large file into 200-line chunks
split -l 200 large_file.py chunk_
for f in chunk_*; do
gemini "Add type hints to this Python snippet" < "$f"
sleep 5
done
3. Switch to a Flash Model
The gemini-2.0-flash model has significantly higher free-tier RPM and TPM limits thangemini-2.0-pro. For tasks that do not require the highest reasoning capability, flash is a practical way to stay within free quotas:
gemini --model gemini-2.0-flash "Summarize this file" < big_doc.txt
Exponential Backoff Strategy
For scripts that process many files, a simple sleep is not enough. You need an exponential backoff strategy that automatically detects a 429 response and retries with progressively longer waits. Google's recommended pattern for API clients is documented in the official retry-strategy guide — the same exponential-backoff-with-jitter approach applies to Gemini API quota errors. The script below is a production-ready wrapper you can drop into any automation:
Exponential backoff works by doubling the wait time after each failure: 2 seconds, then 4, then 8, up to a configurable maximum. Adding a small random jitter (0–1 second) prevents multiple concurrent script instances from retrying at exactly the same moment and overwhelming the API in a burst.
#!/bin/bash
# gemini_with_backoff <prompt> [<input_file>]
gemini_with_backoff() {
local prompt="$1"
local input_file="${2:-}"
local attempt=0
local max_attempts=6
local base_delay=2
while [ $attempt -lt $max_attempts ]; do
if [ -n "$input_file" ] && [ "$input_file" != "-" ]; then
output=$(gemini "$prompt" < "$input_file" 2>&1)
else
output=$(gemini "$prompt" 2>&1)
fi
local exit_code=$?
if [ $exit_code -eq 0 ]; then
echo "$output"
return 0
fi
if echo "$output" | grep -q "429\|rate.limit\|quota"; then
local jitter=$(( RANDOM % 1000 ))
local delay=$(( base_delay * (2 ** attempt) ))
echo "Rate limited. Waiting ${delay}s (attempt $((attempt+1))/$max_attempts)..." >&2
sleep "$(echo "scale=3; $delay + $jitter/1000" | bc)"
attempt=$(( attempt + 1 ))
else
echo "Non-retryable error: $output" >&2
return 1
fi
done
echo "ERROR: max retries reached" >&2
return 1
}
Monitoring Your API Usage
Reactive error handling is useful, but proactive monitoring is better. The Google AI Studio dashboard shows real-time graphs of your RPM, TPM, and RPD consumption. Check it before running large batch jobs so you know how much headroom you have.
For automated scripts, consider logging each API call with a timestamp so you can analyse usage patterns offline. A simple append to a log file takes just one extra line:
# Log every API call with timestamp
echo "$(date -u +'%Y-%m-%dT%H:%M:%SZ') REQUEST model=gemini-2.0-flash prompt_chars=${#PROMPT}" >> ~/.gemini/usage.log
# Count requests in the last minute
awk -v d="$(date -u -d'1 minute ago' +'%Y-%m-%dT%H:%M' 2>/dev/null || date -u -v-1M +'%Y-%m-%dT%H:%M')" \
'$1 > d {count++} END {print count+0, "requests in last 60s"}' ~/.gemini/usage.log
Frequently Asked Questions
What does HTTP 429 Too Many Requests mean in Gemini CLI?
HTTP 429 means you have exceeded one of the rate limits for your API tier — either RPM, TPM, or RPD. Wait for the limit window to reset (usually 60 seconds for minute-level limits) and retry. The response body often includes a retryDelay field with the recommended wait time.
How can I check my remaining API quota?
Visit Google AI Studio and navigate to the API usage section. You can see current RPM, TPM, and daily consumption graphs updated in near real-time. The usage page also shows historical data to help you plan capacity.
Does upgrading to a paid plan immediately remove rate limits?
Upgrading increases your limits significantly, but hard caps still apply even on paid plans. The exact limits depend on the plan tier and the model selected. Pro plans typically offer 10x to 100x higher limits than the free tier, with no daily request cap.
Can I use multiple API keys to avoid rate limits?
Using multiple keys specifically to circumvent rate limits violates Google's API terms of service. The correct approach is to upgrade your plan, implement request throttling, or use exponential backoff to stay within your allocated quota.