Repository navigation
handle error message when the model is experiencing high demand #5937
Description
Describe the Bug:
Went through a quick start and experienced the following error:
errorCode : "ServerError" errorMessage : "503 UNAVAILABLE. {'error': {'code': 503, 'message': 'This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.', 'status': 'UNAVAILABLE'}}"
Steps to Reproduce:
Please provide a numbered list of steps to reproduce the behavior:
- Follow all current Quick Start instructions
- If the model is now experiencing high demand, the error may appear.
Expected and Observed Behavior:
Unable to respond to the user for a short period of time.
Environment Details:
- ADK Library Version : 2.1.0
- Desktop OS: macOS
- Python Version: 3.11
Model Information:
- Are you using LiteLLM: No
- Which model is being used: gemini-2.5-flash
Additional Context:
I suggest trying to add retry configuration to the gemini model in the Quick Start README.md (Agent part) to automatically handle these transient errors, since gemini 2.5 flash can be configured to automatically retry on this error using retry_options parameter in Gemini class.
But overall it is not an urgent bug to be fixed as it is a temporary issue which can resolve itself in a short wait.
How often has this issue occurred?:
Rare, only when the model is in high demand
Activity
surajksharma07 commentedon Jun 2, 2026
@KellySit This looks like a transient 503 from Gemini's side — worth trying: pass retry_options=types.HttpRetryOptions(initial_delay=1, attempts=3) to the Gemini class (from google.genai import types), which lets the SDK automatically retry on these transient failures.
Could you give that a try and let us know if it helps?
KellySit commentedon Jun 3, 2026
@surajksharma07 sure, I can give it a try and I will let you know more later
nicolay-r commentedon Jun 24, 2026
@surajksharma07, I've tried to customize the original
agentexample here in accordance with your comment:And it works on the free-tier API!
surajksharma07 commentedon Jul 13, 2026
Thanks for the independent confirmation @nicolay-r — good to know retry_options holds up on the free tier too!
Worth flagging though: PR #6059 (the actual docs fix) has stalled.
@boyangsvl asked back on Jun 11 for a dedicated retry_options sample instead of editing the main quickstart directly, that's never been addressed,Checked latest main directly: neither README.md nor contributing/samples/core/quickstart/agent.py mention retry_options yet, so this gap is still open through v2.4.0.
@KellySit — are you able to add the dedicated sample so this can finally land, or should someone else pick it up?
Team is looking more into it.
Thanks!
KellySit commentedon Jul 14, 2026
@surajksharma07 sure I can pick this up and have it done soon!
surajksharma07 commentedon Aug 3, 2026
Closing this out — @KellySit, the dedicated sample never landed and #6059 got closed for that same reason, so there's nothing left in flight here.
To be clear, the README and quickstart still don't mention retry_options at latest (v2.6.1), but the workaround itself is solid — confirmed independently by two people now.
Anyone hitting this transient 503 can use retry_options=types.HttpRetryOptions(attempts=3, initial_delay=1.0) on the Gemini model today.
Reopen or send a fresh PR with the dedicated sample anytime if someone wants to pick it back up!