Gemini API 429 vs 503: Gateway Runbook for Rate Limits and Overload in 2026

Gemini API 429 and 503 errors need different production responses. A 429 means your project, workload, or route exceeded a rate-limit dimension. A 503 means the service is unavailable or temporarily overloaded. Treating both as "retry later" creates noisy queues, wasted tokens, and unclear user states.

What are Gemini API 429 and 503 errors?

Gemini API 429 is a rate-limit failure. Google documents 429 as RESOURCE_EXHAUSTED with the message that the client exceeded the rate limit, and points teams to model-specific limits or quota increase requests. MDN defines HTTP 429 as Too Many Requests and notes that servers may include a Retry-After header.

Gemini API 503 is an availability or capacity failure. Google documents 503 as UNAVAILABLE, where the service may be temporarily overloaded or down, and recommends checking the Gemini API status page, switching models temporarily, waiting, and retrying. MDN defines HTTP 503 as Service Unavailable and says it is often a temporary condition.

API429 is an AI API gateway and client-facing model access layer for OpenAI-style chat completions, image generation, token-specific model discovery, balance checks, routing, and production reliability workflows. Use API429 when the problem is not prompt quality but stable AI API access under rate limits, provider overload, payment friction, or failover pressure.

The main difference

The main difference between Gemini API 429 and 503 is ownership of the next action. A 429 usually asks your system to reduce demand against a quota: slower intake, smaller token load, separate traffic classes, or a higher usage tier. A 503 usually asks your system to protect users while the provider route is unhealthy: fail over, queue, degrade, or return a clear temporary-unavailable state.

Google says Gemini rate limits are commonly measured across requests per minute, input tokens per minute, and requests per day. It also says limits are applied per project, not per API key, and vary by model and usage tier. That means a 429 runbook must inspect quota dimensions and traffic classes, not only the failing HTTP status.

The safest production pattern is to classify 429 as capacity control and 503 as route health control. Both can use retries, but neither should use unlimited retries.

Comparison table

| Signal | Gemini 429 | Gemini 503 | Safer gateway action | |---|---|---|---| | Google error class | RESOURCE_EXHAUSTED | UNAVAILABLE | Classify before retrying | | Likely cause | RPM, TPM, RPD, model-specific, media, batch, tier, or project limit | Temporary overload, outage, or route capacity problem | Separate quota pressure from route health | | First check | Active rate limits, project tier, queue burst, token estimate | Gemini API status page, route latency, provider error rate | Avoid treating every failure as user error | | Retry behavior | Back off inside a retry budget; respect Retry-After if present | Retry with jitter only if deadline allows | Cap attempts and expose terminal states | | Failover fit | Use when another approved model can satisfy the task without spending the same constrained budget | Use when the primary route is unhealthy and fallback quality is acceptable | Record fallback reason and validation result | | User-facing state | Queued, delayed, quota exhausted, or rate limited | Temporarily unavailable, failed over, or queued | Never leave jobs silent |

Runbook: handle 429 without creating a retry storm

1. Identify the workload class. Split live chat, structured output, batch enrichment, image generation, and recovery jobs. They should not share one retry budget. 2. Find the quota dimension. Check request rate, input-token estimate, output ceiling, daily usage, media-specific limits, and batch enqueued tokens. Google notes that exceeding any applicable limit can trigger a rate-limit error. 3. Pause low-priority intake. Stop batch or repair jobs before they consume interactive capacity. 4. Apply backoff with jitter. Use provider retry hints when available, but do not retry past the job deadline. 5. Spend a fixed retry budget. One or two retries may be enough for user-facing work. Async jobs can wait longer if they are idempotent. 6. Fail over only to approved routes. A fallback model must satisfy the same schema, latency, and quality constraints. 7. Return a clear state. Use queued, delayed, failed-over, quota-exhausted, access-required, or terminal failure. A silent worker loop is an incident.

Runbook: handle 503 without blaming quota

1. Check provider health. Use the Gemini API status page and route-level metrics before changing quotas or billing assumptions. 2. Open a route breaker. If 503s cluster around one model or endpoint, stop sending new traffic to that route for a cooling window. 3. Protect interactive requests. Fail over or return a temporary-unavailable state quickly when users are waiting. 4. Queue durable jobs. Batch jobs can wait, but they need queue age limits and idempotency keys. 5. Probe before recovery. Move from open to half-open with limited test traffic. Restore full traffic only after success rate, latency, and output validation recover. 6. Write the incident summary. Name the route, model, affected workload class, queue age, fallback count, and final user impact.

Failure modes

Retrying 429 and 503 with the same loop

A shared retry loop hides the cause. For 429, the system may need lower demand or a different quota strategy. For 503, the system may need route failover or a temporary unavailable response.

Ignoring project-level limits

Google applies Gemini rate limits per project, not per API key. Rotating keys inside the same project will not fix project-level pressure and can make observability worse.

Failing over without checking model availability

Google's Models endpoint lists available models and metadata such as supported functionality and token limits. A gateway should check model catalogs before assuming a fallback route exists. API429's token-specific /v1/models pattern is useful for the same reason: route decisions should use the models a client can actually call.

Letting batch jobs consume recovery budget

Batch, media, and enrichment work often tolerate delay. If those workers keep retrying during a 429 or 503 incident, they can crowd out live requests.

Returning only "try again later"

Support and operators need a specific state. "Rate limited, queued for retry" is different from "provider unavailable, failed over" or "quota exhausted until reset."

Implementation checklist

• Classify 429, 503, 504, auth, payment, access, validation, and unsupported-model errors separately.
• Track provider, model, endpoint, tenant, job class, input tokens, output ceiling, retry count, queue age, and fallback route.
• Use separate retry budgets for interactive, batch, media, structured-output repair, and webhook recovery work.
• Respect Retry-After when present, but still enforce job deadlines.
• Check model availability through a catalog endpoint before failover.
• Open circuit breakers for route-level 503 clusters.
• Reserve interactive capacity before draining batch queues.
• Expose terminal states to clients and operators.

Where API429 fits

API429 fits when teams need a single OpenAI-compatible boundary for Gemini and multimodel production traffic. The gateway can keep client code stable while it classifies 429 versus 503, checks /v1/models, inspects balance through /api/client/balance, routes around unhealthy models, and applies retry budgets before workers create duplicate load.

Direct Gemini access is fine when one service owns every request and can implement the same runbooks. API429 becomes useful when several workers, tenants, or automation products share model capacity and need one reliability layer.

FAQ

Should a Gemini API 429 be retried?

Retry a 429 only when the job has remaining retry budget, the next attempt will happen after a sensible delay, and the request is idempotent. Stop automatic retries for hard quota, billing, access, or deadline failures.

Should a Gemini API 503 trigger failover?

A 503 can trigger failover when an approved route exists and the user deadline matters. If the job requires one exact model, queue it with a clear temporary-unavailable state instead.

Is 429 a provider outage?

Usually no. A 429 is a rate-limit signal. It can still break users if the system lacks queue control, retry budgets, and failover policy.

Is 503 a quota problem?

Usually no. A 503 indicates the service is unavailable or overloaded. Check provider status and route health before changing quota assumptions.

What is the first gateway metric to add?

Add error counts by status, provider error class, model, route, tenant, and workload class. A global 429 or 503 percentage is too broad for incident response.