Error Handling
Copyright 2025 Google LLC.
Gemini API: Error handling
This Colab notebook demonstrates strategies for handling common errors you might encounter when working with the Gemini API:
- Transient Errors: Temporary failures due to network issues, server overload, etc.
- Rate Limits: Restrictions on the number of requests you can make within a certain timeframe.
- Timeouts: When an API call takes too long to complete.
You have two main approaches to explore:
- Automatic retries: A simple way to retry requests when they fail due to transient errors.
- Manual backoff and retry: A more customizable approach that provides finer control over retry behavior.
Gemini Rate Limits
The default rate limits for different Gemini models are outlined in the Gemini API model documentation. If your application requires a higher quota, consider requesting a rate limit increase.
Setup your API key
To run the following cells, store your API key in a Colab Secret named GOOGLE_API_KEY. If you don't have an API key or need help creating a Colab Secret, see the Authentication guide.
Automatic retries
The Gemini API's client library offers built-in retry mechanisms for handling transient errors. You can enable this feature by using the request_options argument with API calls like generate_content, generate_answer, embed_content, and generate_content_async.
Advantages:
- Simplicity: Requires minimal code changes for significant reliability gains.
- Robust: Effectively addresses most transient errors without additional logic.
Customize retry behavior:
Use these settings in retry to customize retry behavior:
predicate: (callable) Determines if an exception is retryable. Default:if_transient_errorinitial: (float) Initial delay in seconds before the first retry. Default:1.0maximum: (float) Maximum delay in seconds between retries. Default:60.0multiplier: (float) Factor by which the delay increases after each retry. Default:2.0timeout: (float) Total retry duration in seconds. Default:120.0
'Elara wasn’t looking for magic. She was looking for a backpack. Her old one, affectionately nicknamed “The Beast,” had finally given up the ghost, its seams ripped and its zipper permanently jammed. So, she found herself in Mrs. Willowby’s Oddity Emporium, a place smelling of mothballs and forgotten dreams.\n\nThe backpack in question was tucked away in a dusty corner, almost hidden behind a taxidermied two-headed duck. It was made of a deep indigo fabric, embroidered with silver constellations that shimmered faintly even in the dim light. It was perfect.\n\n“That one’s been here for ages,” Mrs. Willowby croaked, dusting it off with a flourish. “Nobody seems to want it.”\n\nElara didn\'t care. She paid the paltry sum, slung the backpack over her shoulder, and hurried home.\n\nThe first sign that something was amiss came the next day. Packing for school, Elara discovered the backpack was inexplicably larger inside than out. She could fit her textbooks, lunch, a bulky art project, and still have room for more. It was like a miniature, indigo TARDIS.\n\nThen came the apple. She’d absentmindedly tossed an apple into the backpack, then spent the next five minutes searching for it. When she finally gave up, she pulled out her history book – and the apple was perched perfectly on top, gleaming as if freshly polished.\n\nOver the next few weeks, Elara discovered the backpack’s magic was more whimsical than powerful. It couldn\'t grant wishes or transport her to other dimensions, but it could certainly make life interesting. It could produce the exact right color of paint she needed for her art project, always perfectly blended. It could conjure a warm scarf on a chilly day. It could even, on one particularly stressful day, produce a miniature, purring kitten that promptly curled up in her lap.\n\nThe backpack seemed to respond to Elara’s needs, often anticipating them. If she was bored, it would produce a book she\'d been meaning to read. If she was nervous about a test, it would contain a perfectly sharpened pencil and a reassuring note, scrawled in elegant script she didn\'t recognize.\n\nBut the magic wasn\'t always predictable. One day, she reached in for her math textbook and pulled out a handful of sand, complete with a tiny, brightly colored seashell. Another time, expecting her lunch, she found a single, perfectly ripe strawberry.\n\nElara kept the backpack\'s magic a secret. It was her little secret, her personal quirk in a world that often felt mundane. She loved the element of surprise, the anticipation of what the backpack would conjure next.\n\nOne day, however, she overheard a girl in her class, Maya, crying in the hallway. Maya had lost her grandmother\'s locket, a tiny silver heart that was her most treasured possession. Elara hesitated. Could the backpack help?\n\nShe found Maya sitting on a bench, tears streaming down her face. "Maya," she said softly, "I... I might be able to help."\n\nReluctantly, Elara explained about the backpack. Maya looked at her with a mixture of disbelief and hope. Elara unzipped the backpack, her heart pounding. She closed her eyes, pictured the locket, the delicate silver chain, the intricate heart shape. She reached inside.\n\nHer fingers brushed against something cold and smooth. She pulled it out. It was the locket.\n\nMaya gasped, her eyes wide with wonder. "That\'s it! That\'s my locket!" She snatched it from Elara\'s hand and clutched it to her chest. "Thank you," she whispered, tears still falling, but now tears of joy.\n\nFrom that day on, Elara didn\'t keep the backpack\'s magic a secret. She didn\'t advertise it, but when someone needed help, she offered what she could. A lost homework assignment, a forgotten umbrella, a comforting word – the backpack seemed to know exactly what was needed.\n\nThe indigo backpack wasn\'t just a bag; it was a symbol of hope, a reminder that even in the most ordinary of lives, a little bit of magic could make all the difference. And Elara, the girl who had simply been looking for a replacement for "The Beast," had become something much more – a bearer of magic, and a friend to those who needed it most. And she knew, with a certainty that warmed her from the inside out, that the magic of the backpack was only just beginning.\n'
Manually increase timeout when responses take time
If you encounter ReadTimeout or DeadlineExceeded errors, meaning an API call exceeds the default timeout (600 seconds), you can manually adjust it by defining timeout in the request_options argument.
GenerateContentResponse(candidates=[Candidate(content=Content(parts=[Part(video_metadata=None, thought=None, code_execution_result=None, executable_code=None, file_data=None, function_call=None, function_response=None, inline_data=None, text='Flora had always been unremarkable. Brown hair, brown eyes, perpetually lost in a book. Even her backpack, a drab canvas thing she\'d inherited from her older brother, screamed "invisible." Until, one Tuesday morning, it didn\'t.\n\nShe was rushing to catch the bus, her fingers fumbling with the zipper of the aforementioned backpack, when it refused to budge. Frustrated, she yanked harder. There was a ripping sound, but instead of canvas tearing, a shimmering, iridescent light spilled out.\n\nFlora gasped. The inside of the backpack wasn\'t canvas anymore. It was… a swirling vortex of colours, like the aurora borealis compressed into a small space. Hesitantly, she reached in. Her fingers brushed against something soft, and she pulled it out.\n\nIt was a perfect, crimson apple, polished to a gleam. She hadn\'t packed an apple. She hadn\'t packed anything, actually, other than a crumpled textbook and a half-eaten bag of chips. She shrugged and took a bite.\n\nThe apple exploded in her mouth with a flavour she\'d never experienced. It tasted of sunshine, laughter, and the comforting smell of rain on dry earth. She felt a surge of energy, of boundless possibility.\n\nFrom that day on, Flora\'s life was anything but unremarkable. The backpack, it turned out, was magical. Whatever she needed, the backpack provided. Not necessarily what she *wanted*, but what she *needed*.\n\nOne day, facing a daunting math test, she reached in, hoping for a cheat sheet. Instead, she pulled out a skipping rope. Confused, she tucked it into her pocket. During the test, she felt a rising tide of anxiety. On impulse, she pulled out the rope and, ignoring the bewildered stares of her classmates, started skipping in the corner. The rhythm calmed her, cleared her head, and suddenly, the formulas clicked into place. She aced the test.\n\nAnother time, feeling lonely and ignored, she hoped for a new friend. The backpack gave her a packet of wildflower seeds. Disappointed, she almost tossed them aside. But then she remembered the empty patch of dirt behind the school. She planted the seeds, nurtured them, and soon, a riot of colours bloomed. Students, drawn to the vibrant flowers, started talking to her, helping her tend the garden. She found her community.\n\nThe backpack wasn\'t always easy. Sometimes, it gave her things she didn\'t understand or appreciate at first. A rusty key, a chipped teacup, a single, perfect feather. But each time, in its own strange way, the object taught her a lesson, filled a need she didn\'t even know she had.\n\nOne day, rummaging through the backpack for a pen, Flora found something unexpected: a small, leather-bound book. Its pages were blank, but the title was embossed in gold: "The Unwritten Story."\n\nShe understood. The backpack wasn\'t just providing her with objects; it was providing her with opportunities, with the raw materials to build her own extraordinary life. It was up to her to write the story.\n\nFlora closed the book, a smile playing on her lips. She still had brown hair and brown eyes, and she still loved to read. But now, she carried herself with a newfound confidence, a spark of adventure in her eyes. She was no longer invisible. The magic backpack had helped her discover the magic within herself. And the greatest magic of all, she realised, was the power to create her own destiny, one chapter, one challenge, one adventure at a time.\n')], role='model'), citation_metadata=None, finish_message=None, token_count=None, finish_reason=<FinishReason.STOP: 'STOP'>, avg_logprobs=-0.5562713704210647, grounding_metadata=None, index=None, logprobs_result=None, safety_ratings=None)], create_time=None, response_id=None, model_version='gemini-2.0-flash', prompt_feedback=None, usage_metadata=GenerateContentResponseUsageMetadata(cache_tokens_details=None, cached_content_token_count=None, candidates_token_count=752, candidates_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=752)], prompt_token_count=8, prompt_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=8)], thoughts_token_count=None, tool_use_prompt_token_count=None, tool_use_prompt_tokens_details=None, total_token_count=760), automatic_function_calling_history=[], parsed=None)
Caution: While increasing timeouts can be helpful, be mindful of setting them too high, as this can delay error detection and potentially waste resources.
Manually implement backoff and retry with error handling
For finer control over retry behavior and error handling, you can use the retry library (or similar libraries like backoff and tenacity). This gives you precise control over retry strategies and allows you to handle specific types of errors differently.
GenerateContentResponse(candidates=[Candidate(content=Content(parts=[Part(video_metadata=None, thought=None, code_execution_result=None, executable_code=None, file_data=None, function_call=None, function_response=None, inline_data=None, text='Unzip endless possibilities with the Magic Backpack - more space, more adventure!\n')], role='model'), citation_metadata=None, finish_message=None, token_count=None, finish_reason=<FinishReason.STOP: 'STOP'>, avg_logprobs=-0.6894590854644775, grounding_metadata=None, index=None, logprobs_result=None, safety_ratings=None)], create_time=None, response_id=None, model_version='gemini-2.0-flash', prompt_feedback=None, usage_metadata=GenerateContentResponseUsageMetadata(cache_tokens_details=None, cached_content_token_count=None, candidates_token_count=16, candidates_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=16)], prompt_token_count=10, prompt_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=10)], thoughts_token_count=None, tool_use_prompt_token_count=None, tool_use_prompt_tokens_details=None, total_token_count=26), automatic_function_calling_history=[], parsed=None)
Test the error handling with retry mechanism
To validate that your error handling and retry mechanism work as intended, define a generate_content function that deliberately raises a ServiceUnavailable error on the first call. This setup will help you ensure that the retry decorator successfully handles the transient error and retries the operation.
Error: 503 Service Unavailable
'Unzip the impossible with the Magic Backpack - where adventure always fits!\n'