Usa esta guía para diagnosticar y resolver problemas comunes 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 los SDKs de cliente. Nuestros SDKs cliente son de código abierto en los siguientes repositorios:
Si tienes problemas con la clave de API, asegúrate de haberla configurado correctamente según la guía de configuración de claves 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 comunes del backend 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 el formato de la solicitud, los ejemplos y las versiones compatibles. El uso de funciones de una versión más reciente de la API con un extremo más antiguo puede generar 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 donde 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 una clave de API incorrecta. Intentas usar un modelo ajustado sin realizar la autenticación adecuada. | Verifica que tu clave de API esté configurada y tenga el acceso correcto. Además, asegúrate de realizar la autenticación adecuada para usar los modelos ajustados. |
| 404 | NOT_FOUND | No se encontró el recurso solicitado. | No se encontró el 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 del nivel gratuito. | Asegúrate de que tu solicitud esté 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 1.5 Pro a Gemini 1.5 Flash) y comprueba si funciona. O bien espera un momento y vuelve a intentar 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é temporalmente sobrecargado o inactivo. | El servicio se está quedando sin capacidad temporalmente. | Cambia temporalmente a otro modelo (p.ej., de Gemini 1.5 Pro a Gemini 1.5 Flash) y comprueba si funciona. O bien espera un momento y vuelve a intentar 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 procesarse dentro de la fecha límite. | La instrucción (o el contexto) es demasiado grande para procesarla a tiempo. | Establece un "tiempo de espera" más largo en tu solicitud del cliente para evitar este error. |
Verifica si hay errores de parámetros del modelo en tus llamadas a la API
Asegúrate de que los parámetros de tu modelo estén dentro de los siguientes valores:
| Parámetro del modelo | Valores (rango) |
| Recuento de candidatos | Entre 1 y 8 (número entero) |
| Temperatura | 0.0-1.0 |
| Cantidad máxima de tokens de salida |
Usa get_model (Python) 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 correcta de la API (p.ej., /v1 o /v1beta) y un 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 de la API de /v1beta.
Comprueba si tienes el modelo correcto
Asegúrate de usar un modelo compatible que aparezca en nuestra página de modelos.
Problemas de seguridad
Si ves que se bloqueó una solicitud debido a una configuración de seguridad en tu llamada a la API, revisa la solicitud en relación con los filtros que estableciste en la llamada a la API.
Si ves BlockedReason.OTHER, es posible que la consulta o la respuesta infrinjan las Condiciones del Servicio o que no se admitan.
Problema con la recitación
Si ves que el modelo deja de generar resultados debido al motivo RECITATION, esto 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.
Mejora el resultado del modelo
Para obtener resultados de modelos de mayor calidad, explora 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.
Si tienes cientos de ejemplos de buenos pares de entrada y salida, también puedes considerar el ajuste del modelo.
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 algunos idiomas seleccionados. El envío de instrucciones en idiomas no compatibles puede generar respuestas inesperadas o incluso bloqueadas. Consulta los idiomas disponibles para ver actualizaciones.
Informa un error
Únete al debate en el foro para desarrolladores de Google AI si tienes preguntas.