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 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 del servicio de backend de la API de Gemini
En la siguiente tabla, se enumeran los códigos de error de backend comunes que puedes encontrar, junto con explicaciones de sus causas y pasos para solucionar problemas:
| Código HTTP | Estado | Descripción | Ejemplo | Solución |
| 400 | INVALID_ARGUMENT | El cuerpo de la solicitud tiene un formato incorrecto. | Hay un error tipográfico o falta un campo obligatorio en tu solicitud. | Consulta la referencia de la API para obtener información sobre el formato de la solicitud, ejemplos y versiones compatibles. El uso de funciones de una versión de API más reciente con un extremo anterior puede causar errores. |
| 400 | FAILED_PRECONDITION | El nivel gratuito de la API de Gemini no está disponible en tu país. Habilita la facturación en tu proyecto en Google AI Studio. | Estás realizando una solicitud en una región en la que no se admite el nivel gratuito y no habilitaste la facturación en tu proyecto en Google AI Studio. | Para usar la API de Gemini, deberás configurar un plan pagado con Google AI Studio. |
| 403 | PERMISSION_DENIED | Tu clave de API no tiene los permisos necesarios. | Estás usando la clave de API incorrecta; intentas usar un modelo ajustado sin pasar por la autenticación adecuada. | Verifica que tu clave de API esté configurada y tenga el acceso correcto. Asegúrate de pasar por la autenticación adecuada para usar modelos ajustados. |
| 404 | NOT_FOUND | No se encontró el recurso solicitado. | No se encontró un archivo de imagen, audio o video al que se hace referencia en tu solicitud. | Verifica si todos los parámetros de tu solicitud son válidos para tu versión de la API. |
| 429 | RESOURCE_EXHAUSTED | Superaste el límite de frecuencia. | Estás enviando demasiadas solicitudes por minuto con la API de Gemini de nivel gratuito. | Verifica que estés dentro del límite de frecuencia del modelo. Solicita un aumento de la cuota si es necesario. |
| 500 | INTERNAL | Se produjo un error inesperado en Google. | El contexto de entrada es demasiado largo. | Reduce el contexto de entrada o cambia temporalmente a otro modelo (p.ej., de Gemini 2.5 Pro a Gemini 2.5 Flash) y comprueba si funciona. O espera un poco y vuelve a intentar enviar la solicitud. Si el problema persiste después de volver a intentarlo, infórmalo con el botón Enviar comentarios en Google AI Studio. |
| 503 | NO DISPONIBLE | Es posible que el servicio esté sobrecargado o inactivo temporalmente. | El servicio se está quedando sin capacidad temporalmente. | Cambia temporalmente a otro modelo (p.ej., de Gemini 2.5 Pro a Gemini 2.5 Flash) y comprueba si funciona. O espera un poco y vuelve a intentar enviar la solicitud. Si el problema persiste después de volver a intentarlo, infórmalo con el botón Enviar comentarios en Google AI Studio. |
| 504 | DEADLINE_EXCEEDED | El servicio no puede terminar de procesar dentro del plazo. | Tu instrucción (o contexto) es demasiado grande para procesarse a tiempo. | Establece un "tiempo de espera" más largo en tu solicitud del cliente para evitar este error. |
Verifica si hay errores en los parámetros del modelo en tus llamadas a la API
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 (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 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 2.5
Si observas una mayor latencia o uso de tokens con los modelos 2.5 Flash y Pro, esto puede deberse a que vienen con la función de pensamiento habilitada de forma predeterminada para mejorar la calidad. Si priorizas la velocidad o necesitas minimizar los costos, puedes ajustar o inhabilitar el pensamiento.
Consulta la página de pensamiento para obtener orientación y código de muestra.
Problemas de seguridad
Si ves que se bloqueó una instrucción debido a una 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 de 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 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 la salida estructurada
|
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. |
|
| 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 pensamiento.
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 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 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 estén protegidas 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 comunicaremos las actualizaciones lo antes posible.
Medidas de seguridad de Google para claves filtradas
¿Cómo ayudará Google a proteger mi cuenta de la superación 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 el 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 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.
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 producir respuestas inesperadas o incluso bloqueadas. Consulta los idiomas disponibles para obtener actualizaciones.
Informa un error
Únete al debate en el foro para desarrolladores de Google AI si tienes preguntas.