Usa esta guía para diagnosticar y resolver problemas habituales que surgen cuando llamas a la API de Gemini. Es posible que encuentres problemas con el servicio de backend de la API de Gemini o con los SDKs de cliente. Nuestros SDKs para clientes son de código abierto y se encuentran en los siguientes repositorios:
Si tienes problemas con la clave de API, verifica que la hayas configurado correctamente según la guía de configuración de la clave de API.
Códigos de error
Para obtener una referencia completa de todos los códigos de error, incluidos los códigos de estado HTTP, los códigos de generación bloqueada y los códigos de error de contenido, consulta la página Errores de la API.
Estrategia de reintentos
Si recibes un error que indica que debes reintentar la solicitud (como un 429 RESOURCE_EXHAUSTED o un 503 UNAVAILABLE), te recomendamos que implementes una estrategia de retirada exponencial. Esto significa que esperas un tiempo breve antes del primer reintento y, luego, aumentas gradualmente el tiempo de espera entre los reintentos posteriores.
Los SDKs de cliente oficiales para la API de Gemini, como el SDK de Python, incluyen de forma predeterminada una lógica de reintento automática con retirada exponencial para controlar errores transitorios, como tiempos de espera, problemas de red y límites de frecuencia (códigos de estado 429 y 5xx). Por ejemplo, el SDK de Python vuelve a intentar automáticamente hasta cuatro veces los errores transitorios con una demora inicial de aproximadamente 1 segundo y una demora máxima de 60 segundos.
Si realizas solicitudes directas a la API de REST o personalizas tu lógica de reintentos, sigue estas prácticas recomendadas para aumentar la probabilidad de que la solicitud se realice correctamente y evitar sobrecargar el servicio:
- Usar la retirada exponencial: Espera un breve período antes del primer reintento (por ejemplo, 1 segundo) y, luego, aumenta la demora de forma exponencial (por ejemplo, 2 s, 4 s, 8 s).
- Agrega Jitter: Agrega un "Jitter" aleatorio a la demora para evitar que todos los clientes reintenten la acción al mismo tiempo.
- Reintenta en errores específicos: Solo reintenta en errores transitorios (como
429,408o5xx). No reintentes en errores del cliente (como400,402o403), ya que indican problemas como claves de API no válidas, créditos de prepago agotados o sintaxis incorrecta. - Configura la cantidad máxima de reintentos: Define una cantidad máxima de reintentos para evitar bucles infinitos.
Verifica si hay errores en los parámetros del modelo en tus llamadas a la API
Verifica que los parámetros de tu modelo se encuentren dentro de los siguientes valores:
| Parámetro del modelo | Valores (rango) |
| Recuento de candidatos | 1 a 8 (número entero) |
| Temperatura | 0.0-1.0 |
| Cantidad máxima de tokens de salida | Usa la página de modelos para determinar la cantidad máxima de tokens del modelo que usas. |
| TopP | 0.0-1.0 |
Además de verificar los valores de los parámetros, asegúrate de usar la versión de la API correcta (p.ej., /v1 o /v1beta) y el modelo que admite las funciones que necesitas. Por ejemplo, si una función está en versión Beta, solo estará disponible en la versión de la API de /v1beta.
Comprueba si tienes el modelo correcto
Verifica que estés usando un modelo compatible que se encuentre en nuestra página de modelos.
Mayor latencia o uso de tokens con modelos de pensamiento
La mayor latencia o el mayor uso de tokens suelen ocurrir porque los modelos de Gemini 3.x tienen habilitado el pensamiento de forma predeterminada. Los modelos de Gemini 2.5 en desuso también usan el pensamiento predeterminado.
Los modelos de pensamiento generan tokens de razonamiento internos para mejorar la calidad. Este proceso de razonamiento aumenta la latencia de respuesta y el consumo total de tokens.
Si priorizas una latencia más baja o necesitas minimizar los costos, puedes reducir el nivel de pensamiento o desactivarlo.
Para obtener detalles de configuración y muestras de código, consulta la guía de pensamiento.
Problemas de seguridad
Si ves que se bloqueó una instrucción debido a un parámetro de configuración de seguridad en tu llamada a la API, revisa la instrucción en relación con los filtros que estableciste en la llamada a la API.
Si ves BlockedReason.OTHER, es posible que la búsqueda o la respuesta incumplan las condiciones del servicio o que no se admitan.
Problema de recitación
Si ves que el modelo deja de generar resultados debido al motivo de RECITACIÓN, significa que el resultado del modelo puede parecerse a ciertos datos. Para solucionar este problema, intenta que la instrucción o el contexto sean lo más únicos posible y usa una temperatura más alta.
Problema de tokens repetitivos
Si ves tokens de salida repetidos, prueba las siguientes sugerencias para reducirlos o eliminarlos.
| Descripción | Causa | Solución alternativa sugerida |
|---|---|---|
| Guiones repetidos en tablas de Markdown | Esto puede ocurrir cuando el contenido de la tabla es largo, ya que el modelo intenta crear una tabla de Markdown alineada visualmente. Sin embargo, la alineación en Markdown no es necesaria para el procesamiento correcto. |
Agrega instrucciones en tu instrucción para darle al modelo lineamientos específicos para generar tablas en Markdown. Proporciona ejemplos que sigan esos lineamientos. También puedes intentar ajustar la temperatura. Para generar código o resultados muy estructurados, como tablas de Markdown, se ha demostrado que una temperatura alta funciona mejor (>= 0.8). A continuación, se incluye un ejemplo de un conjunto de lineamientos que puedes agregar a tu instrucción para evitar este 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 en tablas de Markdown | Al igual que con los guiones repetidos, esto ocurre cuando el modelo intenta alinear visualmente el contenido de la tabla. La alineación en Markdown no es necesaria para el procesamiento correcto. |
|
Saltos de línea repetidos (\n) en el resultado estructurado
|
Cuando la entrada del modelo contiene secuencias de escape o Unicode, como \u o \t, puede generar saltos de línea repetidos.
|
|
| Texto repetido con salida estructurada | Cuando el resultado del modelo tiene un orden diferente para los campos que el esquema estructurado definido, esto puede generar texto repetido. |
|
| Llamadas a herramientas repetitivas | Esto puede ocurrir si el modelo pierde el contexto de pensamientos anteriores o llama a un extremo no disponible al que se ve obligado a llamar. |
Indícale al modelo que mantenga el estado dentro de su proceso de pensamiento.
Agrega lo siguiente al final de las instrucciones del 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 no forma parte de la salida estructurada | Esto puede ocurrir si el modelo se atasca en una solicitud que no puede resolver. |
|
Claves de API bloqueadas o que no funcionan
En esta sección, se describe cómo verificar si tu clave de la API de Gemini está bloqueada y qué hacer al respecto.
Comprende por qué se bloquean las llaves
Identificamos una vulnerabilidad por la que algunas claves de API podrían haberse expuesto públicamente. Para proteger tus datos y evitar el acceso no autorizado, bloqueamos de forma proactiva estas claves filtradas conocidas para que no puedan acceder a la API de Gemini.
Confirma si tus llaves están afectadas
Si se sabe que se filtró tu clave, ya no podrás usarla con la API de Gemini. Puedes usar Google AI Studio para ver si alguna de tus claves de API está bloqueada para llamar a la API de Gemini y generar claves nuevas. También es posible que veas el siguiente error cuando intentes usar estas claves:
Your API key was reported as leaked. Please use another API key.
Acción para las claves de API bloqueadas
Debes generar nuevas claves de API para tus integraciones de la API de Gemini con Google AI Studio. Te recomendamos que revises tus prácticas de administración de claves de API para asegurarte de que las claves nuevas estén protegidas y no se expongan públicamente.
Cargos inesperados debido a vulnerabilidades
Envía un caso de asistencia para la facturación. Nuestro equipo de facturación está trabajando en este problema y te informaremos las novedades lo antes posible.
Medidas de seguridad de Google para las claves filtradas
¿Cómo me ayudará Google a proteger mi cuenta del abuso y el exceso de costos si se filtran mis claves de API?
- Estamos trabajando para emitir claves de API cuando solicites una nueva clave con Google AI Studio, que, de forma predeterminada, se limitará solo a Google AI Studio y no aceptará claves de otros servicios. Esto ayudará a evitar el uso no deseado de teclas cruzadas.
- De forma predeterminada, bloqueamos las claves de API que se filtran y se usan con la API de Gemini, lo que ayuda a evitar el abuso de los costos y los datos de tu aplicación.
- Podrás encontrar el estado de tus claves de API en Google AI Studio, y trabajaremos para comunicarnos de forma proactiva cuando identifiquemos que se filtraron tus claves de API para que tomes medidas de inmediato.
Mejora el resultado del modelo
Para obtener resultados de mayor calidad, explora la escritura de instrucciones más estructuradas. En la página de la guía de ingeniería de instrucciones, se presentan algunos conceptos básicos, estrategias y prácticas recomendadas para comenzar.
Información sobre los límites de tokens
Lee nuestra Guía de tokens para comprender mejor cómo contar tokens y sus límites.
Problemas conocidos
- La API solo admite una cantidad de idiomas seleccionados. Si envías instrucciones en idiomas no admitidos, es posible que se generen respuestas inesperadas o incluso bloqueadas. Consulta los idiomas disponibles para ver las actualizaciones.
Informar un error
Si tienes preguntas, únete al debate en el foro para desarrolladores de IA de Google.