En esta página, se proporciona información para solucionar problemas relacionados con los códigos de error comunes de los SDKs de Gemini API y Firebase AI Logic.
Error 400: API key not valid. Please pass a valid API key.
Si recibes un error 400 que dice
API key not valid. Please pass a valid API key., suele significar que la
clave de API en tu objeto o archivo de configuración de Firebase no existe o no está configurada
para usarse con tu app o proyecto de Firebase.
Verifica que la clave de API que aparece en el archivo o el objeto de configuración de Firebase coincida con la clave de API de tu app. Puedes ver todas tus claves de API en el panel APIs y servicios > Credenciales de la consola de Google Cloud.
Si descubres que no coinciden, obtén un objeto o archivo de configuración de Firebase nuevo y, luego, reemplaza el que está en tu app. El objeto o archivo de configuración nuevo debe contener una clave de API válida para tu app y proyecto de Firebase.
Error 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Si intentas enviar una solicitud multimodal con una URL de Cloud Storage for Firebase,
es posible que encuentres el siguiente error 400:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Este error se produce cuando un proyecto no tiene los agentes de servicio necesarios aprovisionados de forma automática correctamente cuando se habilitó la API de Agent Platform en el proyecto. Este es un problema conocido con algunos proyectos, y estamos trabajando en una solución global.
Esta es la solución alternativa para corregir tu proyecto y aprovisionar correctamente estos agentes de servicio, de modo que puedas comenzar a incluir URLs de Cloud Storage for Firebase en tus solicitudes multimodales. Debes ser propietario del proyecto y solo debes completar este conjunto de tareas una vez para tu proyecto.
Accede y autentícate con gcloud CLI.
La forma más fácil de hacerlo es desde Cloud Shell. Obtén más información en la documentación de Google Cloud.Si se te solicita, sigue las instrucciones que se muestran en la terminal para que gcloud CLI se ejecute en tu proyecto de Firebase.
Necesitarás el ID de tu proyecto de Firebase, que puedes encontrar en la parte superior de la página settings Configuración del proyecto en Firebase console.
Ejecuta el siguiente comando para aprovisionar los agentes de servicio necesarios en tu proyecto:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
Espera unos minutos para asegurarte de que los agentes de servicio estén aprovisionados y, luego, vuelve a intentar enviar la solicitud multimodal que incluye la URL de Cloud Storage for Firebase.
Si sigues recibiendo este error después de esperar varios minutos, comunícate con el equipo de asistencia de Firebase.
Error 403: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Si recibes un error 403 - PERMISSION_DENIED que dice
To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check,
significa que tu solicitud no tiene un token de App Check válido y estás
intentando acceder a un modelo del que se suele abusar.
Se identificaron algunos modelos generativos como comunes para que los agentes maliciosos los usen de forma inadecuada.
Sin App Check, tu proyecto es vulnerable al abuso de estos modelos. Para ayudar a proteger a nuestros desarrolladores, Firebase bloquea el acceso a estos modelos, a menos que tus solicitudes incluyan un token de App Check válido (lo que requiere que se aplique de manera forzosa la App Check para Firebase AI Logic).
Si quieres acceder al modelo que devolvió el error, haz lo siguiente:
Configura App Check para Firebase AI Logic. Para el desarrollo local, asegúrate de configurar el proveedor de depuración de App Check.
Si ya configuraste App Check, vuelve a verificar que hayas completado todos los pasos de las instrucciones vinculadas.
Vuelve a enviar la solicitud desde tu app a Firebase AI Logic.
Esta solicitud enviará un token de App Check válido y ya no recibirás el error 403.
¿Sigues recibiendo el error 403?
Si se aplica de manera forzosa App Check y enviaste una solicitud, pero sigues recibiendo el error 403, verifica si se aplica de manera forzosa la protección contra repeticiones para Firebase AI Logic (incluido el modo "Solo supervisión").
Cuando se aplica la protección contra repetición, solo los tokens de uso limitado se consideran verificados para Firebase AI Logic, lo que significa que los tokens de sesión normales no pueden borrar este error 403. Para solucionar este problema, realiza una de las siguientes acciones:
Opción 1: Si quieres usar la protección contra repeticiones, vuelve a verificar su configuración.
Asegúrate de haber completado todos los pasos para configurar la protección contra repeticiones, lo que incluye habilitar los tokens de uso limitado en la base de código de tu app.
Vuelve a enviar una solicitud a Firebase AI Logic.
Opción 2: Si no quieres usar la protección contra repetición o no tienes habilitados los tokens de uso limitado en tu app, puedes anular la aplicación de la protección contra repetición.
Anula la aplicación de la protección contra repeticiones en la consola de Firebase: ve a la pestaña Seguridad > Verificación de aplicaciones > APIs, haz clic para expandir la fila Firebase AI Logic, haz clic en Configurar y, luego, anula la aplicación de la protección contra repeticiones en el diálogo.
Vuelve a enviar una solicitud a Firebase AI Logic.
Antes de lanzar tu app para los usuarios finales, debes configurar un proveedor de certificación de producción (como App Attest, Play Integrity o reCAPTCHA Enterprise) para que los usuarios finales puedan acceder a tu función de IA cuando se aplique App Check.
Error 403: PERMISSION_DENIED: Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Si recibes un error 403 - PERMISSION_DENIED que dice
Firebase AI Logic has been deactivated in this project. To resume using
Firebase AI Logic, you must enforce Firebase App Check. Learn more:
https://firebase.google.com/docs/ai-logic/app-check,
significa que tu proyecto de Firebase se identificó como inactivo y las solicitudes
de tu app no tienen un token de App Check válido.
Los "proyectos inactivos" son aquellos que tienen habilitada la Firebase AI Logic, pero no tienen ningún uso reciente de la Firebase AI Logic.
Sin App Check, tu proyecto es vulnerable al abuso de la Gemini API. Para proteger tu proyecto, Firebase desactivó el uso de Firebase AI Logic hasta que tus solicitudes incluyan un token de App Check válido (lo que requiere que se aplique de manera forzosa App Check para Firebase AI Logic).
Cuando quieras volver a usar Firebase AI Logic, haz lo siguiente:
Configura App Check para Firebase AI Logic. Para el desarrollo local, asegúrate de configurar el proveedor de depuración de App Check.
Si ya configuraste App Check, vuelve a verificar que hayas completado todos los pasos de las instrucciones vinculadas.
Vuelve a enviar la solicitud desde tu app a Firebase AI Logic.
Esta solicitud enviará un token de App Check válido y ya no recibirás el error 403.
¿Sigues recibiendo el error 403?
Si se aplica de manera forzosa App Check y enviaste una solicitud, pero sigues recibiendo el error 403, verifica si se aplica de manera forzosa la protección contra repeticiones para Firebase AI Logic (incluido el modo "Solo supervisión").
Cuando se aplica la protección contra repetición, solo los tokens de uso limitado se consideran verificados para Firebase AI Logic, lo que significa que los tokens de sesión normales no pueden borrar este error 403. Para solucionar este problema, realiza una de las siguientes acciones:
Opción 1: Si quieres usar la protección contra repeticiones, vuelve a verificar su configuración.
Asegúrate de haber completado todos los pasos para configurar la protección contra repeticiones, lo que incluye habilitar los tokens de uso limitado en la base de código de tu app.
Vuelve a enviar una solicitud a Firebase AI Logic.
Opción 2: Si no quieres usar la protección contra repetición o no tienes habilitados los tokens de uso limitado en tu app, puedes anular la aplicación de la protección contra repetición.
Anula la aplicación de la protección contra repeticiones en la consola de Firebase: ve a la pestaña Seguridad > Verificación de aplicaciones > APIs, haz clic para expandir la fila Firebase AI Logic, haz clic en Configurar y, luego, anula la aplicación de la protección contra repeticiones en el diálogo.
Vuelve a enviar una solicitud a Firebase AI Logic.
Antes de lanzar tu app para los usuarios finales, debes configurar un proveedor de certificación de producción (como App Attest, Play Integrity o reCAPTCHA Enterprise) para que los usuarios finales puedan acceder a tu función de IA cuando se aplique App Check.
Error 403: PERMISSION_DENIED: The caller does not have permission.
Si recibes un error 403 que dice
PERMISSION_DENIED: The caller does not have permission., suele significar que
la clave de API de tu objeto o archivo de configuración de Firebase pertenece a otro
proyecto de Firebase.
Verifica que la clave de API que aparece en el archivo o el objeto de configuración de Firebase coincida con la clave de API de tu app. Puedes ver todas tus claves de API en el panel APIs y servicios > Credenciales de la consola de Google Cloud.
Si descubres que no coinciden, obtén un objeto o archivo de configuración de Firebase nuevo y, luego, reemplaza el que está en tu app. El objeto o archivo de configuración nuevo debe contener una clave de API válida para tu app y proyecto de Firebase.
Error 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Si recibes un error 403 que dice
Requests to this API firebasevertexai.googleapis.com ... are blocked.,
por lo general, significa que la clave de API de la configuración de Firebase en tu app tiene
restricciones que impiden que llame a la API requerida.
Para solucionar este problema, debes actualizar las restricciones de tu clave de API en la consola de Google Cloud para incluir la API requerida. Para Firebase AI Logic,
debes asegurarte de que la API de Firebase AI Logic
(firebasevertexai.googleapis.com) esté incluida en la lista de APIs
seleccionadas a las que se puede llamar con la clave de API.
Sigue estos pasos:
En la consola de Google Cloud, abre el panel APIs y servicios > Credenciales.
Selecciona la clave de API que tu aplicación está configurada para usar (por ejemplo, la "clave de iOS" para una app para iOS).
En la página Editar clave de API, busca la sección Restricciones de API.
Asegúrate de que esté seleccionada la opción Restringir clave. Si no es así, tu clave no tiene restricciones, y es probable que esta no sea la causa del error.
En el menú desplegable APIs seleccionadas, busca y selecciona la API de Firebase AI Logic para agregarla a la lista de APIs seleccionadas a las que se puede llamar con la clave de API.
Haz clic en Guardar.
Los cambios pueden tardar hasta cinco minutos en aplicarse.
Error 404: Firebase AI Logic genai config not found
Si recibes un error 404 que dice Firebase AI Logic genai config not found,
por lo general, significa que un parámetro de configuración de Firebase AI Logic está mal configurado o
falta.
Estas son las causas más probables de este error:
Aún no configuraste tu proyecto de Firebase para un proveedor de Gemini API.
Qué hacer:
En la consola de Firebase, ve a Servicios de IA > AI Logic. Haz clic en Comenzar y, luego, selecciona el proveedor de Gemini API que elegiste. Habilita la API y Firebase configurará tu proyecto para ese proveedor. Después de completar el flujo de trabajo, vuelve a intentar la solicitud.Si hace poco realizaste el flujo de trabajo de configuración de Firebase AI Logic en la consola de Firebase, es posible que la configuración de Firebase AI Logic aún no esté disponible para todos los servicios de backend requeridos en todas las regiones aplicables.
Qué hacer:
Espera unos minutos y, luego, vuelve a intentar enviar la solicitud.
Error 404: ¿el modelo "was not found or your project does not have access to it"?
Por ejemplo: “Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version.”
Existen diferentes motivos por los que podrías recibir un error como este.
Nombre de modelo no válido
Causa: El nombre del modelo que proporcionaste no es válido.
Solución: Verifica el nombre y la versión del modelo con la lista de todos los modelos compatibles y disponibles. Asegúrate de verificar los segmentos y su orden en el nombre del modelo. Por ejemplo:
- Nombre del modelo de Gemini 4 Hydrogen
más reciente:
gemini-4-hydrogen - Nombre del modelo de Gemini 4 Argon
más reciente:
gemini-4-argon - Nombre del modelo de Gemini 4 Carbon
más reciente:
gemini-4-carbon - Nombre del modelo de Gemini 3.x Flash
más reciente:
gemini-3.8-flash - Nombre del modelo de Gemini 3.x Flash‑Lite
más reciente:
gemini-3.5-flash-lite - Nombre del modelo de Gemini Nano Banana 2.1
más reciente:
gemini-nano-banana-2.1 - Nombre del modelo de Gemini Nano Banana 2
más reciente:
gemini-3.1-flash-image - Nombre del modelo de Gemini Nano Banana 2 Lite
más reciente:
gemini-3.1-flash-lite-image - Nombre del modelo de Gemini Nano Banana Pro
más reciente:
gemini-3-pro-image
- Nombre del modelo de Gemini 4 Hydrogen
más reciente:
Modelo de cierre (retirado)
Causa: El modelo al que intentas acceder superó su fecha de cierre (retiro) y se desactivó de forma permanente (por ejemplo, los modelos Gemini 2.5 de uso general en Agent Platform Gemini API (formerly Vertex AI), los modelos Gemini 2.0 o los modelos Imagen).
Solución: Consulta las Preguntas frecuentes sobre los modelos obsoletos y cerrados y actualiza tu código para usar un modelo de reemplazo activo.
Ubicación no válida (solo se aplica si se usa el proveedor Agent Platform Gemini API (formerly Vertex AI))
Causa: Es posible que tu solicitud intente acceder a un modelo en una ubicación en la que no está disponible.
Solución: Asegúrate de que tu solicitud intente acceder al modelo donde está disponible.
Cuando usas el Agent Platform Gemini API (formerly Vertex AI), puedes especificar una ubicación para acceder al modelo durante la inicialización de forma opcional. Si no especificas una ubicación, Firebase AI Logic se establece de forma predeterminada en las siguientes ubicaciones:
- Cuando uses la sintaxis de inicialización de "Agent Platform":
global - Cuando uses la sintaxis de inicialización heredada de "Vertex AI":
us-central1
Sin embargo, no todos los modelos son compatibles con estas ubicaciones predeterminadas. Esto significa que, según el modelo, es posible que se deba establecer de forma explícita una ubicación específica durante la inicialización.
Modelos Gemini experimentales y de versión preliminar: Solo están disponibles en la ubicación
global.Modelos estables Gemini 4.x y Gemini 3.x: Están disponibles en la ubicación
globaly, a menudo, en las ubicacionesusyeu.Modelos Gemini Live API 2.5: Están disponibles en muchas ubicaciones, pero no en
global. (Ten en cuenta que los modelos de Gemini 2.5 de uso general se cerraron para la Agent Platform Gemini API (formerly Vertex AI)).
- Cuando uses la sintaxis de inicialización de "Agent Platform":
Obtén más información para especificar la ubicación para acceder al modelo (incluidos los fragmentos de código).
Errores 429: "You exceeded your current quota, please check your plan and billing details" o "Resource exhausted, please try again later."
Existen diferentes motivos por los que podrías recibir un error como este.
Estás superando tu cuota o el modelo al que accedes está sobrecargado con solicitudes de otras personas.
La acción que debes realizar depende de si usas Gemini Developer API o Agent Platform Gemini API (formerly Vertex AI). Para obtener más información sobre las cuotas y cómo solicitar cuotas adicionales, consulta Límites de frecuencia y cuotas.
Si usas Agent Platform Gemini API (formerly Vertex AI), la documentación de Google Cloud proporciona contexto y orientación adicionales para el código de error 429.
Estás intentando usar un modelo o una función que requiere facturación, pero tu proyecto de Firebase tiene el plan de precios Spark.
Si usas el Gemini Developer API, puedes obtener acceso limitado a ciertos modelos y acceso a muchas funciones básicas mientras estás en el "nivel gratuito" de Gemini Developer API. Este nivel te permite comenzar sin tener que proporcionar una forma de pago, lo que significa que no necesitas actualizar tu proyecto de Firebase al plan de precios Blaze de pago por uso.
Algunos modelos no están disponibles en el "nivel gratuito" de Gemini Developer API y requieren el "nivel pagado", lo que significa que tu proyecto debe tener el plan de precios Blaze de pago por uso. Por ejemplo, los siguientes modelos casi siempre requieren facturación:
- La mayoría de los modelos de versión preliminar y experimentales
- Modelos de generación de contenido multimedia (como los modelos de Gemini Nano Banana)
Algunos modelos ofrecen algunas funciones básicas en el "nivel gratuito" de Gemini Developer API, pero luego requieren el "nivel pagado" para usar funciones más avanzadas. Por ejemplo:
- Cuando se usa la mayoría de los modelos de Gemini 3.x,
la fundamentación con
Google Search oGoogle Maps requiere facturación.
- Cuando se usa la mayoría de los modelos de Gemini 3.x,
la fundamentación con
Obtén información sobre los planes de precios de Firebase y el Gemini Developer API.
Para obtener más detalles, consulta la Gemini Developer API documentación de precios y las preguntas frecuentes sobre facturación.