Usa esta guía para diagnosticar y resolver los problemas habituales que surgen cuando cuando llames a la API de Gemini. A un alto nivel, puedes encontrar problemas el servicio de backend de la API de Gemini o los SDK de cliente. Los SDK de nuestros clientes con código abierto en los siguientes repositorios:
- generative-ai-python
- generative-ai-js
- generative-ai-android
- generative-ai-swift
- generative-ai-dart
- generative-ai-go
Si encuentras problemas con la clave de API, asegúrate de haber configurado tu clave de API de forma correcta 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
La siguiente tabla enumera los códigos de error de backend comunes que puedes encontrar, junto con 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 es incorrecto. | Tu solicitud contiene un error tipográfico o falta un campo obligatorio. | Consulta la referencia de la API para ver el formato de solicitud, los ejemplos y las versiones compatibles. Usar funciones de una versión de API más reciente con un extremo más antiguo 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 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 la clave de API incorrecta. tú intentan usar un modelo ajustado sin pasar por la autenticación adecuada. | Verifica que tu clave de API esté configurada y tenga el acceso correcto. Y asegúrate de realizar la autenticación adecuada para usar modelos ajustados. |
| 404 | NOT_FOUND | No se encontró el recurso solicitado. | No se encontró ningún 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 la versión de tu API. |
| 429 | RESOURCE_EXHAUSTED | Superaste el límite del porcentaje. | Estás enviando demasiadas solicitudes por minuto con la API de Gemini de nivel gratuito. | Asegúrate de estar 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 espera un momento y vuelve a enviar la solicitud. Si el problema persiste después de volver a intentarlo, infórmalo con el botón Enviar comentarios de Google AI Studio. |
| 503 | NO DISPONIBLE | El servicio puede estar temporalmente sobrecargado o inactivo. | Por el momento, la capacidad del servicio se está agotando. | Cambia temporalmente a otro modelo (p.ej., de Gemini 1.5 Pro a Gemini 1.5 Flash) y comprueba si funciona. O espera un momento y vuelve a enviar la solicitud. Si el problema persiste después de volver a intentarlo, infórmalo con el botón Enviar comentarios de 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 procesarla a tiempo. | Establece un "tiempo de espera" mayor en la solicitud del cliente para evitar este error. |
Códigos de error del SDK cliente de Python
En la siguiente tabla, se enumeran los tipos de Error del SDK de cliente de Python códigos que puedas encontrar, junto con explicaciones de sus causas:
| Tipo de error o excepción | Clase | Descripción |
|---|---|---|
| BlockedPromptException | google.generativeai.types.BlockedPromptException | El mensaje se bloqueó por razones de seguridad. |
| BrokenResponseError | google.generativeai.types.BrokenResponseError | Una respuesta de transmisión no funciona. Se genera cuando se accede a algo que requiere la respuesta completa, como el historial de chat. Consulta los detalles del error que se proporcionan en el seguimiento de pila. |
| IncompleteIterationError | google.generativeai.types.IncompleteIterationError | Se genera cuando se accede a algo que requiere una respuesta de la API completa, pero una respuesta de transmisión no se iteró por completo. Llama a resolve() en el objeto de respuesta para consumir el iterador. |
| StopCandidateException | google.generativeai.types.StopCandidateException | La API respondió con un finish_reason excepcional. Revisa el motivo y obtén consejos sobre cómo proceder. |
| PermissionDenied | google.api_core.exceptions.PermissionDenied | No tienes permiso para el recurso solicitado (p.ej., modelo). |
| ResourceExhausted | google.api_core.exceptions.ResourceExhausted | Se agotó tu cuota. Espera un momento y vuelve a intentarlo. Considera configurar reintentos automatizados para manejar estos errores. |
| AlreadyExists | google.api_core.exceptions.AlreadyExists | Ya existe un modelo ajustado con el mismo ID. Especifica un ID de modelo único cuando ajustes un modelo nuevo. |
| InvalidArgument | google.api_core.exceptions.InvalidArgument | Argumento no válido. Un ejemplo es que el archivo es demasiado grande y supera el límite de tamaño de la carga útil. Otro es proporcionar una clave de API no válida. |
| DefaultCredentialsError | google.auth.exceptions.DefaultCredentialsError | La autenticación falla. Verifica tu clave de API y vuelve a intentarlo. |
| RetryError | google.api_core.exceptions.RetryError | Puede producirse cuando se usa un proxy que no admite gRPC. Intenta usar el transporte de REST con genai.configure(..., transport="rest"). |
Revisa tus llamadas a la API en busca de errores de parámetros del modelo
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 | 1-8 (número entero) |
| Temperatura | 0.0 a 1.0 |
| Cantidad máxima de tokens de salida |
Usa
get_model (Python)
para determinar la cantidad máxima de tokens
para el modelo que estás usando.
|
| TopP | 0.0 a 1.0 |
Además de verificar los valores de los parámetros, asegúrate de usar el
Versión de la API (p.ej., /v1 o /v1beta) y
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 /v1beta.
Comprueba si tienes el modelo correcto
Asegúrate de usar un modelo compatible que se encuentra en nuestra página de modelos.
Problemas de seguridad
Si ves que un mensaje se bloqueó 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 infrinjan los términos.
de servicio o no serán compatibles de otro modo.
Problema con la lectura
Si ves que el modelo deja de generar resultados por el motivo RECITATION, significa que la salida del modelo puede parecerse a ciertos datos. Para solucionar esto, intenta hacer mensaje o contexto que sea lo más único posible y use una temperatura más alta.
Mejora la salida del modelo
Para obtener resultados de modelos de mayor calidad, explora la posibilidad de escribir instrucciones más estructuradas. El En la página de introducción al diseño de instrucciones, se presenta algunos conceptos básicos, estrategias y prácticas recomendadas para empezar.
Si tienes cientos de ejemplos de buenos pares de entrada/salida, también puedes considera el ajuste de modelos.
Información sobre los límites de tokens
Para comprender mejor cómo hacerlo, lee nuestra guía sobre tokens. para contar tokens y sus límites.
Problemas conocidos
- La API solo admite algunos idiomas seleccionados. Envía instrucciones en los idiomas no compatibles pueden producir respuestas inesperadas o incluso bloqueadas. Consulta idiomas disponibles para recibir actualizaciones.
Informa un error
Únete al debate en el foro para desarrolladores de IA de Google. si tienes preguntas.