Troubleshooting guide

Use this guide to help you diagnose and resolve common issues that arise when you call the Gemini API. You may encounter issues from either the Gemini API backend service or the client SDKs. Our client SDKs are open sourced in the following repositories:

• python-genai
• js-genai
• go-genai

If you encounter API key issues, verify that you have set up your API key correctly per the API key setup guide.

Error codes

For a complete reference of all error codes, including HTTP status codes, generation blocked codes, and content error codes, see the API errors page.

Retry strategy

If you receive an error indicating that you should retry your request (such as a 429 RESOURCE_EXHAUSTED or 503 UNAVAILABLE), we recommend implementing an exponential backoff strategy. This means you wait a short time before the first retry, and then gradually increase the wait time between subsequent retries.

The official client SDKs for the Gemini API, such as the Python SDK, include automatic retry logic with exponential backoff by default for handling transient errors like timeouts, network issues, and rate limits (429 and 5xx status codes). For example, the Python SDK automatically retries transient errors up to four times with an initial delay of approximately 1 second and a maximum delay of 60 seconds.

If you are making direct REST API requests or customizing your retry logic, follow these best practices to increase the likelihood of a successful request and prevent overwhelming the service:

• Use exponential backoff: Wait a short time before the first retry (for example, 1 second), then increase the delay exponentially (for example, 2s, 4s, 8s).
• Add jitter: Add random "jitter" to the delay to help prevent all clients from retrying at the exact same time.
• Retry on specific errors: Only retry on transient errors (like 429, 408, or 5xx). Do not retry on client errors (like 400 or 403) as they indicate issues like invalid API keys or bad syntax.
• Set maximum retries: Define a maximum number of retry attempts to prevent infinite loops.

Check your API calls for model parameter errors

Verify that your model parameters are within the following values:

In addition to checking parameter values, make sure you're using the correct API version (e.g., /v1 or /v1beta) and model that supports the features you need. For example, if a feature is in Beta release, it will only be available in the /v1beta API version.

Check if you have the right model

Verify that you are using a supported model listed on our models page.

Higher latency or token usage with 2.5 models

If you're observing higher latency or token usage with the 2.5 Flash and Pro models, this can be because they come with thinking is enabled by default in order to enhance quality. If you are prioritizing speed or need to minimize costs, you can adjust or disable thinking.

Refer to thinking page for guidance and sample code.

Safety issues

If you see a prompt was blocked because of a safety setting in your API call, review the prompt with respect to the filters you set in the API call.

If you see BlockedReason.OTHER, the query or response may violate the terms of service or be otherwise unsupported.

Recitation issue

If you see the model stops generating output due to the RECITATION reason, this means the model output may resemble certain data. To fix this, try to make prompt / context as unique as possible and use a higher temperature.

Repetitive tokens issue

If you see repeated output tokens, try the following suggestions to help reduce or eliminate them.

          # Markdown Table Format
          
          * Separator line: Markdown tables must include a separator line below
            the header row. The separator line must use only 3 hyphens per
            column, for example: |---|---|---|. Using more hypens like
            ----, -----, ------ can result in errors. Always
            use |:---|, |---:|, or |---| in these separator strings.

            For example:

            | Date | Description | Attendees |
            |---|---|---|
            | 2024-10-26 | Annual Conference | 500 |
            | 2025-01-15 | Q1 Planning Session | 25 |

          * Alignment: Do not align columns. Always use |---|.
            For three columns, use |---|---|---| as the separator line.
            For four columns use |---|---|---|---| and so on.

          * Conciseness: Keep cell content brief and to the point.

          * Never pad column headers or other cells with lots of spaces to
            match with width of other content. Only a single space on each side
            is needed. For example, always do "| column name |" instead of
            "| column name                |". Extra spaces are wasteful.
            A markdown renderer will automatically take care displaying
            the content in a visually appealing form.