Usa esta guía para diagnosticar y resolver problemas habituales que surgen cuando llamas a la API de Gemini. Es posible que tengas problemas con el servicio de backend de la API de Gemini o con los SDK de cliente. Nuestros SDK de cliente son de código abierto 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 de errores de la API.
Estrategia de reintentos
Si recibes un error que indica que debes reintentar tu solicitud (como 429 RESOURCE_EXHAUSTED o 503 UNAVAILABLE), te recomendamos que implementes una estrategia de retirada exponencial. Esto significa que esperas un breve período antes del primer reintento y, luego, aumentas gradualmente el tiempo de espera entre los reintentos posteriores.
Los SDK de cliente oficiales para la API de Gemini, como el SDK de Python, incluyen lógica de reintento automático con retirada exponencial de forma predeterminada para controlar errores transitorios, como tiempos de espera, problemas de red y límites de frecuencia (429 y 5xx códigos de estado). Por ejemplo, el SDK de Python reintenta automáticamente los errores transitorios hasta cuatro veces 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 reintento, sigue estas prácticas recomendadas para aumentar la probabilidad de que la solicitud se realice correctamente y evitar sobrecargar el servicio:
- Usa 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 fluctuación: Agrega una "fluctuación" aleatoria a la demora para evitar que todos los clientes reintenten al mismo tiempo.
- Reintenta en errores específicos: Solo reintenta en errores transitorios (como
429,408o5xx). No reintentes en errores del cliente (como400o403), ya que indican problemas como claves de API no válidas o sintaxis incorrecta. - Establece reintentos máximos: Define una cantidad máxima de intentos de reintento para evitar bucles infinitos.
Verifica tus llamadas a la API para detectar errores en los parámetros del modelo
Verifica que los parámetros del modelo estén dentro de los siguientes valores:
| Parámetro del modelo | Valores (intervalo) |
| Recuento de candidatos | 1-8 (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 para el modelo que estás usando. |
| 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 admita las funciones que necesitas. Por ejemplo, si una función está en versión beta, solo estará disponible en la versión /v1beta de la API.
Verifica si tienes el modelo correcto
Verifica que estés usando un modelo compatible que aparece en nuestra página de modelos.
Mayor latencia o uso de tokens con modelos de razonamiento
La mayor latencia o uso de tokens suele ocurrir porque los modelos de Gemini 3.x tienen el razonamiento habilitado de forma predeterminada. Los modelos de Gemini 2.5 obsoletos también usan el razonamiento predeterminado.
Los modelos de razonamiento generan tokens de razonamiento interno 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 razonamiento o desactivarlo.
Para obtener detalles de configuración y muestras de código, consulta la guía de razonamiento.
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 con respecto a los filtros que estableciste en la llamada a la API.
Si ves BlockedReason.OTHER, es posible que la consulta o la respuesta incumplan las condiciones
del servicio o no sean compatibles.
Problema de recitación
Si ves que el modelo deja de generar resultados debido al motivo RECITATION, 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 una renderización correcta. |
Agrega instrucciones en tu instrucción para darle al modelo lineamientos específicos para generar tablas de 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 demostró que las temperaturas altas funcionan mejor (>= 0.8). A continuación, se muestra 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 una renderización correcta. |
|
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 el resultado estructurado | Cuando el resultado del modelo tiene un orden diferente para los campos que el esquema estructurado definido, esto puede generar texto repetido. |
|
| Llamada repetitiva a la herramienta | Esto puede ocurrir si el modelo pierde el contexto de los pensamientos anteriores o llama a un extremo no disponible al que se ve obligado a llamar. |
Indica al modelo que mantenga el estado dentro de su proceso de razonamiento.
Agrega esto 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 del resultado estructurado | 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 API de Gemini está bloqueada y qué hacer al respecto.
Comprende por qué se bloquean las claves
Identificamos una vulnerabilidad en 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 accedan a la API de Gemini.
Confirma si tus claves se ven 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. Es posible que también veas el siguiente error cuando intentes usar estas claves:
Your API key was reported as leaked. Please use another API key.
Acción para claves de API bloqueadas
Debes generar claves de API nuevas 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 tus claves nuevas se mantengan seguras y no se expongan públicamente.
Cargos inesperados debido a una vulnerabilidad
Envía un caso de asistencia para la facturación. Nuestro equipo de facturación está trabajando en esto y te informaremos las actualizaciones lo antes posible.
Medidas de seguridad de Google para claves filtradas
¿Cómo ayudará Google a proteger mi cuenta de la sobrecarga de costos y el abuso si se filtran mis claves de API?
- Estamos avanzando hacia la emisión de claves de API cuando solicitas una clave nueva 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 cualquier uso no intencional de claves 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 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 modelos de mayor calidad, explora cómo escribir 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.
Comprende 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. Enviar instrucciones en idiomas no compatibles puede generar respuestas inesperadas o incluso bloqueadas. Consulta los idiomas disponibles para obtener actualizaciones.
Informar un error
Únete al debate en el foro para desarrolladores de Google AI si tienes preguntas.