spb/doc-api

1Use this guide to help you diagnose and resolve common issues that arise when2you call the Gemini API. You may encounter issues from either3the Gemini API backend service or the client SDKs. Our client SDKs are4open sourced in the following repositories:56- [python-genai](https://github.com/googleapis/python-genai)7- [js-genai](https://github.com/googleapis/js-genai)8- [go-genai](https://github.com/googleapis/go-genai)910If you encounter API key issues, verify that you have set up11your API key correctly per the [API key setup guide](https://ai.google.dev/gemini-api/docs/api-key).1213## Error codes1415For a complete reference of all error codes, including HTTP status codes,16generation blocked codes, and content error codes, see the17[API errors](https://ai.google.dev/gemini-api/docs/api-errors) page.1819## Retry strategy2021If 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.2223The official client SDKs for the Gemini API, such as the [Python SDK](https://github.com/googleapis/python-genai), 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.2425If 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:2627- **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).28- **Add jitter:** Add random "jitter" to the delay to help prevent all clients from retrying at the exact same time.29- **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.30- **Set maximum retries:** Define a maximum number of retry attempts to prevent infinite loops.3132## Check your API calls for model parameter errors3334Verify that your model parameters are within the following values:3536|---|---|37| **Model parameter** | **Values (range)** |38| Candidate count | 1-8 (integer) |39| Temperature | 0.0-1.0 |40| Max output tokens | Use the [models page](https://ai.google.dev/gemini-api/docs/models/gemini) to determine the maximum number of tokens for the model you are using. |41| TopP | 0.0-1.0 |4243In addition to checking parameter values, make sure you're using the correct44[API version](https://ai.google.dev/gemini-api/docs/api-versions) (e.g., `/v1` or `/v1beta`) and45model that supports the features you need. For example, if a feature is in Beta46release, it will only be available in the `/v1beta` API version.4748## Check if you have the right model4950Verify that you are using a supported model listed on our [models51page](https://ai.google.dev/gemini-api/docs/models/gemini).5253## Higher latency or token usage with thinking models5455Higher latency or token usage often occurs because Gemini 3.x models have56thinking enabled by default. Deprecated Gemini 2.5 models also use default57thinking.5859Thinking models generate internal reasoning tokens to improve quality. This60reasoning process increases both response latency and total token consumption.6162If you prioritize lower latency or need to minimize costs, you can lower the63thinking level or turn off thinking.6465For configuration details and code samples, see the66[thinking guide](https://ai.google.dev/gemini-api/docs/thinking#thinking-levels).6768## Safety issues6970If you see a prompt was blocked because of a safety setting in your API call,71review the prompt with respect to the filters you set in the API call.7273If you see `BlockedReason.OTHER`, the query or response may violate the [terms74of service](https://ai.google.dev/terms) or be otherwise unsupported.7576## Recitation issue7778If you see the model stops generating output due to the RECITATION reason, this79means the model output may resemble certain data. To fix this, try to make80prompt / context as unique as possible and use a higher temperature.8182> [!NOTE]83> The \`temperature\`, \`top_p\`, and \`top_k\` parameters control how the model generates responses. Although you can modify these parameters, we strongly recommend keeping them at their default values for Gemini 3.x models. Changing these parameters (for example, setting the temperature below 1.0) can cause unexpected behavior, such as looping or degraded performance, particularly in complex mathematical or reasoning tasks.8485## Repetitive tokens issue8687If you see repeated output tokens, try the following suggestions to help88reduce or eliminate them.8990| Description | Cause | Suggested workaround |91| Repeated hyphens in Markdown tables | This can occur when the contents of the table are long as the model tries to create a visually aligned Markdown table. However, the alignment in Markdown is not necessary for correct rendering. | Add instructions in your prompt to give the model specific guidelines for generating Markdown tables. Provide examples that follow those guidelines. You can also try adjusting the temperature. For generating code or very structured output like Markdown tables, high temperature have shown to work better (\>= 0.8). The following is an example set of guidelines you can add to your prompt to prevent this issue: ``` # 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. ``` |92| Repeated tokens in Markdown tables | Similar to the repeated hyphens, this occurs when the model tries to visually align the contents of the table. The alignment in Markdown is not required for correct rendering. | - Try adding instructions like the following to your system prompt: ``` FOR TABLE HEADINGS, IMMEDIATELY ADD ' |' AFTER THE TABLE HEADING. ``` - Try adjusting the temperature. Higher temperatures (\>= 0.8) generally helps to eliminate repetitions or duplication in the output. |93| Repeated newlines (`\n`) in structured output | When the model input contains unicode or escape sequences like `\u` or `\t`, it can lead to repeated newlines. | - Check for and replace forbidden escape sequences with UTF-8 characters in your prompt. For example, `\u` escape sequence in your JSON examples can cause the model to use them in its output too. - Instruct the model on allowed escapes. Add a system instruction like this: ``` In quoted strings, the only allowed escape sequences are \\, \n, and \". Instead of \u escapes, use UTF-8. ``` |94| Repeated text in using structured output | When the model output has a different order for the fields than the defined structured schema, this can lead to repeating text. | - Don't specify the order of fields in your prompt. - Make all output fields required. |95| Repetitive tool calling | This can occur if the model loses the context of previous thoughts and/or call an unavailable endpoint that it's forced to. | Instruct the model to maintain state within its thought process. Add this to the end of your system instructions: ``` When thinking silently: ALWAYS start the thought with a brief (one sentence) recap of the current progress on the task. In particular, consider whether the task is already done. ``` |96| Repetitive text that's not part of structured output | This can occur if the model gets stuck on a request that it can't resolve. | - If thinking is turned on, avoid giving explicit orders for how to think through a problem in the instructions. Just ask for the final output. - Try a higher temperature \>= 0.8. - Add instructions like "Be concise", "Don't repeat yourself", or "Provide the answer once". |97|---|---|---|9899## Blocked or non-working API keys100101This section describes how to check whether your Gemini API key is blocked102and what to do about it.103104### Understand why keys are blocked105106We have identified a vulnerability where some API keys may have been publicly107exposed. To protect your data and prevent unauthorized access, we have108proactively blocked these known leaked keys from accessing the Gemini API.109110### Confirm if your keys are affected111112If your key is known to be leaked, you can no longer use that key with the113Gemini API. You can use [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-keys) to see if any of114your API keys are blocked from calling the Gemini API and generate new115keys. You may also see the following error returned when attempting to use116these keys:117118    Your API key was reported as leaked. Please use another API key.119120### Action for blocked API keys121122You should generate new API keys for your Gemini API integrations using [Google123AI Studio](https://ai.google.dev/gemini-api/docs/api-keys). We strongly recommend reviewing your API124key management practices to ensure that your new keys are kept secure and are125not publicly exposed.126127### Unexpected charges due to vulnerability128129[Submit a billing support case](https://console.cloud.google.com/support/chat).130Our billing team is working on this, and we will communicate updates as soon as131possible.132133### Google's security measures for leaked keys134135**How is Google going to help secure my account from cost overrun and abuse if136my API keys are leaked?**137138- We are moving towards issuing API keys when you request a new key using [Google AI Studio](https://ai.google.dev/gemini-api/docs/api-keys) that will by default be limited to only Google AI Studio and not accept keys from other services. This will help prevent any unintended cross-key usage.139- We are defaulting to blocking API keys that are leaked and used with the Gemini API, helping prevent abuse of cost and your application data.140- You will be able to find the status of your API keys within [Google AI141  Studio](https://ai.google.dev/gemini-api/docs/api-keys) and we will work on communicating proactively when we identify your API keys are leaked for immediate action.142143## Improve model output144145For higher quality model outputs, explore writing more structured prompts. The146[prompt engineering guide](https://ai.google.dev/gemini-api/docs/prompting-strategies) page147introduces some basic concepts, strategies, and best practices to get you148started.149150## Understand token limits151152Read through our [Token guide](https://ai.google.dev/gemini-api/docs/tokens) to better understand how153to count tokens and their limits.154155## Known issues156157- The API supports only a number of select languages. Submitting prompts in unsupported languages can produce unexpected or even blocked responses. See [available languages](https://ai.google.dev/gemini-api/docs/models#supported-languages) for updates.158159## File a bug160161Join the discussion on the162[Google AI developer forum](https://discuss.ai.google.dev)163if you have questions.