Use este guia para diagnosticar e resolver problemas comuns que surgem ao chamar a API Gemini. Você pode encontrar problemas no serviço de back-end da API Gemini ou nos SDKs do cliente. Nossos SDKs do cliente são de código aberto nos seguintes repositórios:
Se você encontrar problemas com a chave de API, verifique se ela foi configurada corretamente de acordo com o guia de configuração da chave de API.
Códigos de erro
Para uma referência completa de todos os códigos de erro, incluindo códigos de status HTTP, códigos de geração bloqueada e códigos de erro de conteúdo, consulte a página de erros da API.
Repetir estratégia
Se você receber um erro indicando que precisa repetir a solicitação (como um 429 RESOURCE_EXHAUSTED ou 503 UNAVAILABLE), recomendamos implementar uma estratégia de espera exponencial. Isso significa que você espera um pouco antes da primeira nova tentativa e, em seguida, aumenta gradualmente o tempo de espera entre as novas tentativas.
Os SDKs do cliente oficiais da API Gemini, como o SDK do Python, incluem a lógica de repetição automática com espera exponencial por padrão para lidar com erros temporários, como tempos limite, problemas de rede e limites de taxa (429 e 5xx códigos de status). Por exemplo, o SDK do Python repete automaticamente erros temporários até quatro vezes com um atraso inicial de aproximadamente 1 segundo e um atraso máximo de 60 segundos.
Se você estiver fazendo solicitações diretas da API REST ou personalizando a lógica de repetição, siga estas práticas recomendadas para aumentar a probabilidade de uma solicitação bem-sucedida e evitar sobrecarregar o serviço:
- Use a espera exponencial:espere um pouco antes da primeira nova tentativa (por exemplo, 1 segundo) e aumente o atraso exponencialmente (por exemplo, 2s, 4s, 8s).
- Adicione instabilidade:adicione "instabilidade" aleatória ao atraso para evitar que todos os clientes tentem novamente ao mesmo tempo.
- Repita em erros específicos:repita apenas em erros temporários (como
429,408ou5xx). Não repita em erros do cliente (como400ou403), porque eles indicam problemas como chaves de API inválidas ou sintaxe incorreta. - Defina o número máximo de novas tentativas:defina um número máximo de tentativas para evitar loops infinitos.
Verificar se há erros de parâmetro do modelo nas chamadas de API
Verifique se os parâmetros do modelo estão dentro dos seguintes valores:
| Parâmetro do modelo | Valores (intervalo) |
| Contagem de candidatos | 1-8 (inteiro) |
| Temperatura | 0,0-1,0 |
| Máximo de tokens de saída | Use a página de modelos para determinar o número máximo de tokens do modelo que você está usando. |
| TopP | 0,0-1,0 |
Além de verificar os valores dos parâmetros, confira se você está usando a
versão correta da API (por exemplo, /v1 ou /v1beta) e o
modelo que oferece suporte aos recursos necessários. Por exemplo, se um recurso estiver na versão Beta, ele só estará disponível na versão /v1beta da API.
Verificar se você tem o modelo certo
Verifique se você está usando um modelo compatível listado na nossa página de modelos.
Maior latência ou uso de tokens com modelos de raciocínio
A maior latência ou uso de tokens geralmente ocorre porque os modelos do Gemini 3.x têm o raciocínio ativado por padrão. Os modelos descontinuados do Gemini 2.5 também usam o raciocínio padrão.
Os modelos de raciocínio geram tokens de raciocínio internos para melhorar a qualidade. Esse processo de raciocínio aumenta a latência de resposta e o consumo total de tokens.
Se você priorizar uma latência menor ou precisar minimizar os custos, poderá diminuir o nível de raciocínio ou desativá-lo.
Para detalhes de configuração e exemplos de código, consulte o guia de raciocínio.
Problemas de segurança
Se você vir um comando bloqueado devido a uma configuração de segurança na chamada de API, revise o comando em relação aos filtros definidos na chamada de API.
Se você vir BlockedReason.OTHER, a consulta ou resposta poderá violar os termos
de serviço ou não ter suporte.
Problema de recitação
Se o modelo parar de gerar saída devido ao motivo RECITATION, isso significa que a saída do modelo pode se assemelhar a determinados dados. Para corrigir isso, tente tornar o comando / contexto o mais exclusivo possível e use uma temperatura mais alta.
Problema de tokens repetitivos
Se você vir tokens de saída repetidos, tente as sugestões a seguir para ajudar a reduzir ou eliminar esses tokens.
| Descrição | Causa | Alternativa |
|---|---|---|
| Hífens repetidos em tabelas Markdown | Isso pode ocorrer quando o conteúdo da tabela é longo, já que o modelo tenta criar uma tabela Markdown alinhada visualmente. No entanto, o alinhamento no Markdown não é necessário para a renderização correta. |
Adicione instruções ao comando para dar ao modelo diretrizes específicas para gerar tabelas Markdown. Forneça exemplos que sigam essas diretrizes. Você também pode tentar ajustar a temperatura. Para gerar código ou saída muito estruturada, como tabelas Markdown, a temperatura alta funciona melhor (>= 0,8). Confira a seguir um exemplo de diretrizes que você pode adicionar ao comando para evitar esse problema:
# 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.
|
| Tokens repetidos em tabelas Markdown | Semelhante aos hífens repetidos, isso ocorre quando o modelo tenta alinhar visualmente o conteúdo da tabela. O alinhamento no Markdown não é necessário para a renderização correta. |
|
Quebras de linha repetidas (\n) na saída estruturada
|
Quando a entrada do modelo contém sequências de escape ou Unicode, como
\u ou \t, isso pode levar a quebras de linha repetidas.
|
|
| Texto repetido ao usar saída estruturada | Quando a saída do modelo tem uma ordem diferente para os campos do esquema estruturado definido, isso pode levar à repetição de texto. |
|
| Chamada de ferramenta repetitiva | Isso pode ocorrer se o modelo perder o contexto de pensamentos anteriores e/ou chamar um endpoint indisponível ao qual ele é forçado. |
Instrua o modelo a manter o estado no processo de raciocínio.
Adicione isso ao final das instruções do sistema:
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.
|
| Texto repetitivo que não faz parte da saída estruturada | Isso pode ocorrer se o modelo ficar preso em uma solicitação que não pode ser resolvida. |
|
Chaves de API bloqueadas ou não funcionais
Esta seção descreve como verificar se a chave de API Gemini está bloqueada e o que fazer a respeito.
Entender por que as chaves são bloqueadas
Identificamos uma vulnerabilidade em que algumas chaves de API podem ter sido expostas publicamente. Para proteger seus dados e evitar acesso não autorizado, bloqueamos proativamente essas chaves vazadas conhecidas para impedir o acesso à API Gemini.
Confirmar se as chaves foram afetadas
Se a chave for conhecida como vazada, não será mais possível usá-la com a API Gemini. Você pode usar Google AI Studio para verificar se alguma das suas chaves de API está bloqueada para chamar a API Gemini e gerar novas chaves. O seguinte erro também pode ser retornado ao tentar usar essas chaves:
Your API key was reported as leaked. Please use another API key.
Ação para chaves de API bloqueadas
Gere novas chaves de API para suas integrações da API Gemini usando Google AI Studio. Recomendamos revisar as práticas de gerenciamento de chaves de API para garantir que as novas chaves sejam mantidas em segurança e não sejam expostas publicamente.
Cobranças inesperadas devido à vulnerabilidade
Envie um caso de suporte de faturamento. Nossa equipe de faturamento está trabalhando nisso e vamos comunicar as atualizações assim que possível.
Medidas de segurança do Google para chaves vazadas
Como o Google vai ajudar a proteger minha conta contra estouro de custos e abuso se minhas chaves de API forem vazadas?
- Estamos caminhando para emitir chaves de API quando você solicitar uma nova chave usando o Google AI Studio que será limitada apenas ao Google AI Studio por padrão e não aceitará chaves de outros serviços. Isso ajuda a evitar o uso não intencional de chaves cruzadas.
- Estamos bloqueando por padrão as chaves de API vazadas e usadas com a API Gemini, ajudando a evitar o abuso de custos e os dados do aplicativo.
- Você poderá encontrar o status das suas chaves de API no Google AI Studio, e vamos trabalhar para comunicar proativamente quando identificarmos que suas chaves de API foram vazadas para ação imediata.
Melhorar a saída do modelo
Para saídas de modelo de maior qualidade, tente escrever comandos mais estruturados. A página do guia de engenharia de comandos apresenta alguns conceitos básicos, estratégias e práticas recomendadas para você começar.
Entender os limites de tokens
Leia nosso guia de tokens para entender melhor como contar tokens e os limites deles.
Problemas conhecidos
- A API oferece suporte apenas a alguns idiomas selecionados. O envio de comandos em idiomas não compatíveis pode produzir respostas inesperadas ou até mesmo bloqueadas. Consulte os idiomas disponíveis para atualizações.
Informar um bug
Participe da discussão no fórum de desenvolvedores da IA do Google se tiver dúvidas.