diff --git a/README.md b/README.md index 5677c0479..b0e2bec81 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ Here are the recent additions and updates to the Gemini API and the Cookbook: * [Grounding](./quickstarts/Grounding.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Grounding.ipynb): Discover different ways to ground Gemini's answer using different tools, from Google Search to Youtube and URLs and the new [**Maps grounding**](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Grounding.ipynb#maps_grounding) tool. * [Batch API](./quickstarts/Batch_mode.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Batch_mode.ipynb): Use Batch API to send large volume of non-time-sensitive requests to the model and get up to 90% discount. * [Logs and datasets](./examples/Datasets.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/examples/Datasets.ipynb): Process and evaluate your collected logs using the Batch API. + * **Handling Errors and Retries:** Learn how to configure retry logic with exponential backoff to handle rate limits and transient errors. [Guide](./quickstarts/Handling_Errors_and_Retries.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Handling_Errors_and_Retries.ipynb)

@@ -68,7 +69,9 @@ Then, explore the other quickstarts tutorials to learn about individual features * [Get started with Imagen](./quickstarts/Get_started_imagen.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_imagen.ipynb) and [Native image generation](./quickstarts/Get_Started_Nano_Banana.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_Started_Nano_Banana.ipynb): Get started with our image generation capabilities * [Grounding](./quickstarts/Grounding.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Grounding.ipynb): use Google Search for grounded responses * [Code execution](./quickstarts/Code_Execution.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Code_Execution.ipynb): Generate and run Python code to solve complex tasks and even output graphs +* [Handling Errors and Retries](./quickstarts/Handling_Errors_and_Retries.ipynb) [![Colab](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Handling_Errors_and_Retries.ipynb): Learn how to handle rate limits and transient errors using built-in retry logic. * And [many more](https://github.com/google-gemini/cookbook/tree/main/quickstarts/) +

## 2. Examples (Practical Use Cases) diff --git a/quickstarts/Get_started.ipynb b/quickstarts/Get_started.ipynb index 9747c19df..e5260bddc 100644 --- a/quickstarts/Get_started.ipynb +++ b/quickstarts/Get_started.ipynb @@ -126,7 +126,7 @@ }, "outputs": [], "source": [ - "%pip install -U -q 'google-genai>=1.51.0' # 1.51 is needed for Gemini 3 pro thinking levels support" + "%pip install -U -q 'google-genai>=1.51.0' # >=1.21.1 is needed for retry support; 1.51.0 is needed for Gemini 3 Pro thinking levels" ] }, { @@ -559,7 +559,7 @@ " display(Markdown(part.text))\n", " print()\n", "\n", - "print(f\"Used {response.usage_metadata.thoughts_token_count} tokens for the thinking phase and {response.usage_metadata.prompt_token_count} for the output.\")" + "print(f\"The model used {response.usage_metadata.thoughts_token_count} tokens for the thinking phase and {response.usage_metadata.prompt_token_count} for the output.\")" ] }, { @@ -3576,7 +3576,7 @@ " display(Markdown(part.text))\n", " print()\n", "\n", - "print(f\"Used {response.usage_metadata.thoughts_token_count} tokens for the thinking phase and {response.usage_metadata.prompt_token_count} for the output.\")" + "print(f\"The model used {response.usage_metadata.thoughts_token_count} tokens for the thinking phase and {response.usage_metadata.prompt_token_count} for the output.\")" ] }, { @@ -3700,6 +3700,35 @@ "More details on the [documentation](https://ai.google.dev/gemini-api/docs/gemini-3?thinking=explicit#thought_signatures)." ] }, + { + "cell_type": "markdown", + "metadata": { + "id": "7174d850e188" + }, + "source": [ + "## Handle Errors and Retries\n", + "\n", + "When building production applications, API requests can occasionally fail due to rate limits (HTTP `429`) or temporary server-side overloads (HTTP `5xx`). The `google-genai` SDK provides built-in support for automatic retries through the `HttpRetryOptions` configuration. \n", + "\n", + "For a much deeper dive into different error types, when to retry, and how to build custom exponential backoff loops, see the dedicated [Handling Errors and Retries](Handling_Errors_and_Retries.ipynb) guide." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "de30bf8c7cd6" + }, + "outputs": [], + "source": [ + "# Initialize the client with a basic retry policy for transient errors\n", + "client = genai.Client(\n", + " http_options=types.HttpOptions(\n", + " retry_options=types.HttpRetryOptions(attempts=3, initial_delay=2.0)\n", + " )\n", + ")" + ] + }, { "cell_type": "markdown", "metadata": { diff --git a/quickstarts/Handling_Errors_and_Retries.ipynb b/quickstarts/Handling_Errors_and_Retries.ipynb new file mode 100644 index 000000000..600b2bc58 --- /dev/null +++ b/quickstarts/Handling_Errors_and_Retries.ipynb @@ -0,0 +1,294 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": { + "id": "3c5dbcc9ae0c" + }, + "source": [ + "##### Copyright 2025 Google LLC." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "e426989b", + "metadata": { + "cellView": "form", + "id": "ffabf965472d" + }, + "outputs": [], + "source": [ + "# @title Licensed under the Apache License, Version 2.0 (the \"License\");\n", + "# you may not use this file except in compliance with the License.\n", + "# You may obtain a copy of the License at\n", + "#\n", + "# https://www.apache.org/licenses/LICENSE-2.0\n", + "#\n", + "# Unless required by applicable law or agreed to in writing, software\n", + "# distributed under the License is distributed on an \"AS IS\" BASIS,\n", + "# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n", + "# See the License for the specific language governing permissions and\n", + "# limitations under the License." + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "57c4e9f53bb1" + }, + "source": [ + "# Handling Errors and Retries with the Gemini API\n", + "\n", + "" + ] + }, + { + "cell_type": "markdown", + "id": "9a9a229b", + "metadata": { + "id": "b4fb8a01d330" + }, + "source": [ + "When building applications with the Gemini API, requests can occasionally fail. Understanding *why* a request failed is crucial because it dictates how your code should react. \n", + "\n", + "For a full list of API errors, review the [Gemini API Troubleshooting Documentation](https://ai.google.dev/gemini-api/docs/troubleshooting).\n", + "\n", + "## Error Types: When to Retry vs. When to Stop\n", + "\n", + "Not all errors should trigger a retry. If your prompt contains invalid parameters, retrying the exact same request will result in the exact same error, wasting time and resources. \n", + "\n", + "**Errors you SHOULD retry (Transient Errors):**\n", + "* **`429` (Resource Exhausted):** You have exceeded your rate limit or quota. *Action:* Pause and retry using exponential backoff.\n", + "* **`500` (Internal Error) & `503` (Service Unavailable):** The model is temporarily overloaded or experiencing a glitch. *Action:* Pause and retry.\n", + "* **`502` (Bad Gateway) & `504` (Gateway Timeout):** These are temporary network errors that occur between the client and the Google API frontend. Because these are usually caused by transient congestion or connection blips, they often resolve themselves in a matter of seconds. Action: Pause and retry.\n", + "\n", + "**Errors you SHOULD NOT retry (Client Errors):**\n", + "* **`400` (Bad Request):** Invalid parameters, unsupported model, or a prompt that is too long. *Action:* Stop. Fix the code or prompt before sending again.\n", + "* **`403` (Forbidden):** Invalid API key or permission denied. *Action:* Stop. Check your credentials.\n", + "* **`404` (Not Found):** The requested resource (e.g., a specific model name, a file in the File API, or a deleted cache) could not be found. Action: Stop. Verify the model name or resource ID." + ] + }, + { + "cell_type": "markdown", + "id": "016ad8cb", + "metadata": { + "id": "61bd8ec2ebd8" + }, + "source": [ + "\n", + "## Setup" + ] + }, + { + "cell_type": "markdown", + "id": "dbb75afe", + "metadata": { + "id": "3eeaea0c235c" + }, + "source": [ + "### Install SDK\n", + "\n", + "Install the SDK from [PyPI](https://github.com/googleapis/python-genai). It's recommended to always use the latest version." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1ae64aba", + "metadata": { + "id": "78bd0a6c0973" + }, + "outputs": [], + "source": [ + "%pip install -U -q 'google-genai>=1.51.0'" + ] + }, + { + "cell_type": "markdown", + "id": "4af1143b", + "metadata": { + "id": "58994e6dce7a" + }, + "source": [ + "### Setup your API key\n", + "\n", + "To run the following cell, your API key must be stored in a Colab Secret named `GEMINI_API_KEY`. If you don't already have an API key, or you're not sure how to create a Colab Secret, see [Authentication](./Authentication.ipynb) for an example." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "978668a1", + "metadata": { + "id": "f591a97f76c3" + }, + "outputs": [], + "source": [ + "from google.colab import userdata\n", + "\n", + "GEMINI_API_KEY = userdata.get('GEMINI_API_KEY')" + ] + }, + { + "cell_type": "markdown", + "id": "eebd4846", + "metadata": { + "id": "fdd10cf335cd" + }, + "source": [ + "### Choose a model\n", + "\n", + "Select the model you want to use in this guide. You can either select one from the list or enter a model name manually. Keep in mind that some models, such as the 2.5 ones are thinking models and thus take slightly more time to respond. For more details, you can see [thinking notebook ![image](https://storage.googleapis.com/generativeai-downloads/images/colab_icon16.png)](./Get_started_thinking.ipynb) to learn how to control the thinking.\n", + "\n", + "Feel free to select [Gemini 3 Pro](https://ai.google.dev/gemini-api/docs/models#gemini-3-pro) if you want to try our newest model, but keep in mind that it has no free tier.\n", + "\n", + "For a full overview of all Gemini models, check the [documentation](https://ai.google.dev/gemini-api/docs/models/gemini)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a5665419", + "metadata": { + "id": "1d8e3d32b024" + }, + "outputs": [], + "source": [ + "MODEL_ID = \"gemini-3-flash-preview\" # @param [\"gemini-2.5-flash-lite\", \"gemini-3.1-flash-lite-preview\", \"gemini-2.5-flash\", \"gemini-3-flash-preview\", \"gemini-2.5-pro\", \"gemini-3.1-pro-preview\"] {\"allow-input\":true, \"isTemplate\": true}" + ] + }, + { + "cell_type": "markdown", + "id": "ebcf2ed7", + "metadata": { + "id": "fb06b64b8c96" + }, + "source": [ + "## Method 1: Use Built-in SDK HttpRetryOptions\n", + "\n", + "For standard use cases, the `google-genai` SDK handles retries automatically. Configure the `HttpRetryOptions` when initializing the client. The SDK will automatically catch `429` and `5xx` errors and apply exponential backoff under the hood." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7aff7f2c", + "metadata": { + "id": "f1c25d1b6186" + }, + "outputs": [], + "source": [ + "from google import genai\n", + "from google.genai import types\n", + "\n", + "client = genai.Client(\n", + " api_key=GEMINI_API_KEY,\n", + " http_options=types.HttpOptions(\n", + " retry_options=types.HttpRetryOptions(\n", + " attempts=5, \n", + " initial_delay=2.0, \n", + " max_delay=60.0, \n", + " http_status_codes=[429, 500, 502, 503, 504] \n", + " )\n", + " )\n", + ")\n", + "\n", + "response = client.models.generate_content(\n", + " model=MODEL_ID,\n", + " contents='Explain exponential backoff in one sentence.'\n", + ")\n", + "print(response.text)" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "867006d54746" + }, + "source": [ + "## Method 2: Custom Error Handling and Backoff\n", + "\n", + "For complex applications, you may want precise control over the retry logic. The following example demonstrates how to catch the `errors.APIError` exception, inspect the specific HTTP status code, and execute a custom exponential backoff loop based on the error type." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "id": "35d2402cdb4c" + }, + "outputs": [], + "source": [ + "from google import genai\n", + "from google.genai import errors\n", + "import time\n", + "\n", + "# Re-initialize a standard client without automatic retries\n", + "client = genai.Client(api_key=GEMINI_API_KEY)\n", + "\n", + "max_retries = 4\n", + "base_delay = 2.0\n", + "\n", + "for attempt in range(max_retries):\n", + " try:\n", + " response = client.models.generate_content(\n", + " model=MODEL_ID,\n", + " contents='Write a short poem about resilience.'\n", + " )\n", + " print(\"Success!\\n\")\n", + " print(response.text)\n", + " break # Break out of the loop if successful\n", + "\n", + " except errors.APIError as e:\n", + " print(f\"Attempt {attempt + 1} failed. Error Code: {e.code} - {e.message}\")\n", + " \n", + " # Check if it is a transient error that can be retried\n", + " if e.code in [429, 500, 502, 503, 504]:\n", + " delay = base_delay * (2 ** attempt) # Exponential backoff (2s, 4s, 8s...)\n", + " print(f\"Transient error detected. Retrying in {delay} seconds...\\n\")\n", + " time.sleep(delay)\n", + " \n", + " # If it is a client error (e.g., 400 Bad Request), retrying won't help!\n", + " elif e.code in [400, 403, 404]:\n", + " print(\"Fatal client error detected. Please fix your request parameters. Stopping retries.\")\n", + " break\n", + " \n", + " else:\n", + " print(\"Unexpected error encountered. Stopping retries.\")\n", + " break\n", + "else:\n", + " print(\"Maximum retries reached. The request ultimately failed.\")" + ] + }, + { + "cell_type": "markdown", + "metadata": { + "id": "cdd9de6428f6" + }, + "source": [ + "## Next steps\n", + "\n", + "\n", + "\n", + "* [Prompting Strategies](./Prompting.ipynb): Learn how to craft better prompts to minimize errors and improve response quality.\n", + "* [Functional Calling](./Function_calling.ipynb): Teach the model how to use external tools and APIs when it encounters tasks it cannot solve alone.\n", + "* [Context Caching](./Caching.ipynb): Learn how to reduce costs and latency for large prompts by caching frequently used data.\n", + "\n", + "Also check the other Gemini capabilities that you can find in the [Gemini quickstarts](https://github.com/google-gemini/cookbook/tree/main/quickstarts/)." + ] + } + ], + "metadata": { + "colab": { + "name": "Handling_Errors_and_Retries.ipynb", + "toc_visible": true + }, + "kernelspec": { + "display_name": "Python 3", + "name": "python3" + } + }, + "nbformat": 4, + "nbformat_minor": 0 +} diff --git a/quickstarts/README.md b/quickstarts/README.md index 7126880d8..c63648261 100644 --- a/quickstarts/README.md +++ b/quickstarts/README.md @@ -78,3 +78,4 @@ These guides will walk you through the various use cases of the Gemini API: | [Embeddings](./Embeddings.ipynb) | Create high quality and task-specific embeddings. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-gemini/cookbook/blob.ipynb) | | [Video](./Video_understanding.ipynb) | Upload a video to the Gemini API and use it in your prompt. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Video_understanding.ipynb) | | [AI Tutors with LearnLM](./Get_started_LearnLM.ipynb) | Demonstrates how to craft AI tutoring experiences using system instructions aligned with learning science principles. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_LearnLM.ipynb) | +| [Handling Errors and Retries](./Handling_Errors_and_Retries.ipynb) | Learn how to configure retry logic with exponential backoff to handle rate limits and transient errors. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Handling_Errors_and_Retries.ipynb) |