Si Gemini API devuelve un 400, 403 o 404, revisa la petición y el acceso antes de repetirla. Si devuelve un 429, averigua qué límite has alcanzado. Para fallos transitorios 500, 503 o 504, prueba con pocos reintentos y una espera creciente. Ninguna de estas categorías garantiza que la siguiente llamada vaya a funcionar.
Esta guía se centra en Gemini Developer API, incluidas las llamadas generateContent. Los códigos de la aplicación Gemini, Gemini CLI y los servicios de Enterprise necesitan su propio contexto. Conserva el estado HTTP, el mensaje recibido, el modelo y el método: un número aislado no basta para diagnosticar el fallo.
Identifica el error antes de cambiar el código
La primera decisión es si debes corregir algo, esperar a que se libere capacidad o detener el trabajo hasta recuperar acceso o cuota. Esta tabla resume la ruta inicial; el cuerpo de la respuesta decide los detalles.
| Estado HTTP | Qué debes comprobar primero | Próxima acción |
|---|---|---|
| 400 | Campos, formato, parámetros y requisitos de la operación | Corrige la petición o el requisito indicado antes de repetirla. |
| 401 | Credencial ausente o no válida | Comprueba cómo llega la clave al proceso. |
| 402 | Saldo de prepago, cuando el servicio devuelve este código | Revisa la facturación; un bucle de reintentos no repone saldo. |
| 403 | Permisos, restricciones de clave, acceso del proyecto o recurso | Sigue el motivo concreto del mensaje; no regeneres claves por defecto. |
| 404 | Identificador del modelo, versión de API o recurso referenciado | Comprueba que existen y que corresponden al método utilizado. |
| 429 | Límite temporal, cuota diaria u otra restricción de uso | Reduce el ritmo o espera al restablecimiento que corresponda. |
| 500, 503, 504 | Fallo interno, indisponibilidad o plazo de ejecución agotado | Aplica reintentos limitados y comprueba si el fallo depende de la petición. |
| 501 | Función no implementada o no admitida | Revisa la compatibilidad; no lo trates como un fallo transitorio genérico. |
La referencia oficial de errores describe específicamente el formato de Interactions API, con identificadores como rate_limit_exceeded dentro de error.code. En otras llamadas y versiones del SDK puedes encontrar códigos enteros y estados como RESOURCE_EXHAUSTED o PERMISSION_DENIED. No construyas un detector que dé por hecho que todos los endpoints devuelven el mismo JSON.
Antes de probar cambios, guarda una muestra del error sin credenciales ni contenido privado. Anota la hora con zona horaria, proyecto, modelo, método, versión del SDK y número de intentos. Si hay un identificador de solicitud o una indicación de espera, consérvalos también. Evita copiar todas las cabeceras: pueden contener datos de autenticación.
Error 429: separa el ritmo de llamadas de la cuota agotada
Un 429 por exceso de solicitudes en una ventana breve permite reducir el ritmo y volver a intentarlo; una cuota diaria agotada exige esperar al reinicio o conseguir un límite mayor. No basta con añadir una pausa fija a todas las llamadas.
Gemini aplica límites independientes de solicitudes por minuto (RPM), tokens de entrada por minuto (TPM) y solicitudes por día (RPD), entre otros. Se aplican al proyecto, no a cada clave. Consulta los valores activos de tu modelo y nivel en Google AI Studio, siguiendo la documentación de límites; una tabla antigua no describe necesariamente tu proyecto.
| Lo que indica el error o la métrica | Cambio útil | Qué no resuelve ese límite |
|---|---|---|
| Demasiadas solicitudes por minuto | Pon las llamadas en una cola, limita la concurrencia y reparte los envíos. | Cambiar de clave dentro del mismo proyecto. |
| Demasiados tokens de entrada por minuto | Reduce el contexto innecesario y distribuye las peticiones grandes en el tiempo. | Reducir solo el número de llamadas si cada una sigue aportando demasiados tokens. |
| Cuota diaria agotada | Suspende esos trabajos hasta el reinicio o revisa las opciones de ampliación. | Reintentar cada pocos segundos. |
| Límite de gasto por intervalo | Revisa el límite aplicable y suaviza el consumo dentro de esa ventana. | Suponer que disponer de saldo elimina cualquier límite de uso. |
El límite diario RPD se restablece a medianoche del Pacífico. Si programas la reanudación desde España, calcula el instante con la zona America/Los_Angeles: no fijes una hora española permanente, porque los cambios de horario de verano no coinciden siempre. La capacidad indicada tampoco constituye una garantía de disponibilidad. Fuente: límites de Gemini API.
Además, determinadas cuentas tienen límites de gasto en una ventana móvil de diez minutos. Su aplicación depende de las condiciones de la cuenta. Este mecanismo es distinto del saldo de prepago y de un presupuesto mensual: puede explicar un 429 aunque el número de solicitudes parezca pequeño.
¿Por qué aparece un 429 si el panel muestra poco uso?
Un panel con poco uso no identifica por sí solo la causa. Comprueba que estás comparando el mismo proyecto, modelo, métrica e intervalo temporal que aparecen en el error. Revisa también cuántas solicitudes reales produce una acción de tu aplicación: los reintentos del SDK, de una cola y de un proxy pueden sumarse.
Hay otra distinción relevante para las métricas: la guía de claves indica que las peticiones con claves de autorización no se registran en las métricas de uso de cuentas de servicio de Cloud. Esto no significa que todas las métricas de AI Studio estén vacías ni demuestra que sea la causa de tu caso. Fuente: tipos de claves de Gemini API.
Si el mensaje no aclara qué límite se ha alcanzado, conserva una muestra reproducible y contrástala con los límites activos. No asumas un «429 fantasma» ni un plazo de recuperación de quince minutos: no hay una solución universal basada únicamente en ese síntoma.
Error 403: comprueba la clave y después el proyecto
Un 403 indica que la operación no está autorizada. La clave puede ser válida y, aun así, el proyecto, la cuenta de facturación o el recurso solicitado carecer de acceso. La guía oficial de proyectos restringidos distingue estos casos.
Empieza por la configuración que utiliza realmente el servidor. Confirma que la clave pertenece al proyecto esperado y que el proceso recibe la variable correcta, sin imprimir su valor. Si dejas que el SDK detecte las variables automáticamente y existen tanto GOOGLE_API_KEY como GEMINI_API_KEY, da prioridad a GOOGLE_API_KEY. Los ejemplos de esta página pasan explícitamente GEMINI_API_KEY para evitar esa ambigüedad. Fuente: configuración de claves.
Comprueba después el tipo de clave y sus restricciones. Google distingue claves estándar y claves de autorización vinculadas a una cuenta de servicio; las nuevas claves creadas en AI Studio desde el 28 de mayo de 2026 son de autorización. Las claves estándar sin restricciones se rechazan, mientras que las estándar restringidas siguen admitidas. No elimines las restricciones de seguridad como remedio general para un 403: configura el acceso a la API prevista según la guía vigente de claves.
Si el mensaje señala una clave filtrada o bloqueada, revócala o sustitúyela según corresponda y corrige dónde se expuso. Si señala una restricción del proyecto, regenerar otra clave del mismo proyecto no cambia su elegibilidad. No todos los proyectos pueden usar el nivel gratuito; cuando se requiere una cuenta de facturación de pago activa, el uso pasa a facturarse y no desbloquea una nueva cuota gratuita. Una suspensión del proyecto o de la facturación requiere resolver ese estado concreto. Fuente: acceso y facturación del proyecto.
Comprueba también la ubicación real desde la que se ejecuta la petición. España figura entre las regiones disponibles, pero el idioma de la aplicación no determina dónde está tu servidor. Activar la facturación no es un método general para habilitar regiones no admitidas.
Si puedes listar modelos, ¿por qué no puedes generar contenido?
Una respuesta 200 de models.list no demuestra que el proyecto tenga acceso a la inferencia. Google aclara que listar modelos comprueba la existencia de la clave, pero no la elegibilidad del proyecto ni su facturación. generateContent, streamGenerateContent e Interactions realizan otras comprobaciones. Fuente: suspensión del proyecto o de la cuenta de facturación.
Tras corregir el acceso, una petición mínima de generación permite comprobar esa operación concreta. Hazla solo si puedes autorizar su posible coste y conserva el resultado; listar modelos y generar contenido son pruebas diferentes.
Errores 400 y 404: reduce la petición y verifica los identificadores
Ante un 400, lee el campo o requisito mencionado por el error. Empieza con el modelo deseado y una entrada de texto sencilla, sin parámetros opcionales. Si esa petición funciona, incorpora de uno en uno los archivos, herramientas y opciones que necesita tu aplicación. Así podrás relacionar el fallo con un cambio concreto.
No apliques ajustes universales de temperatura. La compatibilidad de temperature, top_p y top_k depende del modelo y puede cambiar entre generaciones. Comprueba la sección oficial sobre parámetros del modelo y utiliza los valores predeterminados cuando no necesites modificarlos. Un FAILED_PRECONDITION exige revisar el requisito señalado, como el acceso o la facturación, además del formato de la petición.
Ante un 404, contrasta el identificador exacto con el catálogo de modelos, la versión de API y el método. Si una integración antigua ha dejado de funcionar, revisa también el ciclo de vida de los modelos. No sustituyas a ciegas el modelo por uno de un tutorial anterior: puede tener restricciones de acceso o haber cambiado de disponibilidad.
Si la petición incluye archivos subidos, verifica su identificador, el proyecto y sus metadatos con files.get. Los archivos de Files API se eliminan automáticamente tras 48 horas. Un recurso caducado debe volver a subirse cuando siga siendo necesario; quitarlo de la petición podría hacer que el modelo respondiera a una tarea distinta. Fuente: conservación y eliminación de archivos.
Reintentos en Python y Node.js sin multiplicar las peticiones
Los SDK actuales ya incluyen reintentos. Configura esa capa antes de añadir otro bucle en tu aplicación: tres intentos del SDK dentro de tres intentos externos pueden producir hasta nueve llamadas para una sola operación. La estrategia oficial recomienda limitar los intentos y usar espera exponencial con variación aleatoria para que los clientes no vuelvan a enviar todos a la vez.
Estos ejemplos usan tres intentos totales, incluido el primero, y reintentan únicamente 500, 503 y 504. Excluyen 429 de forma deliberada: una lista de estados HTTP no distingue una saturación breve de una cuota diaria agotada. Una vez identificado un límite temporal, puedes incluir 429 en esa lista, manteniendo la cola de envío y un máximo de intentos. Para una cuota agotada, deja la operación suspendida hasta que se restablezca.
Utilizamos google-genai y @google/genai, las bibliotecas oficiales actuales. Los paquetes antiguos google-generativeai y @google/generative-ai ya no son la opción mantenida para estos ejemplos.
Python
Instala google-genai en el entorno de tu aplicación. Configura GEMINI_API_KEY mediante tu gestor de secretos o entorno y asigna a GEMINI_MODEL un identificador disponible para tu proyecto. Guarda el código como consulta.py y ejecútalo con python consulta.py.
python -m pip install google-genaiimport os
from google import genai
from google.genai import errors, types
def consultar():
api_key = os.environ["GEMINI_API_KEY"]
model = os.environ["GEMINI_MODEL"]
options = types.HttpOptions(
timeout=30_000,
retry_options=types.HttpRetryOptions(
attempts=3,
initial_delay=1.0,
max_delay=8.0,
exp_base=2.0,
jitter=1.0,
http_status_codes=[500, 503, 504],
),
)
with genai.Client(api_key=api_key, http_options=options) as client:
try:
response = client.models.generate_content(
model=model,
contents="Responde con una frase breve de saludo.",
)
except errors.APIError as exc:
# No se imprime la clave ni el contenido de la petición.
print(f"La petición ha fallado. Código HTTP: {exc.code}")
return False
if not response.text:
print("Se recibió una respuesta sin texto; revisa sus metadatos.")
return False
print(response.text)
return True
if __name__ == "__main__":
raise SystemExit(0 if consultar() else 1)Node.js
Instala @google/genai, configura las mismas dos variables y guarda este ejemplo como consulta.mjs. Ejecútalo con node consulta.mjs en un entorno Node compatible con la versión del paquete instalada.
npm install @google/genaiimport { ApiError, GoogleGenAI } from "@google/genai";
const apiKey = process.env.GEMINI_API_KEY;
const model = process.env.GEMINI_MODEL;
if (!apiKey || !model) {
throw new Error("Configura GEMINI_API_KEY y GEMINI_MODEL.");
}
const ai = new GoogleGenAI({
apiKey,
httpOptions: {
timeout: 30_000,
retryOptions: {
attempts: 3,
initialDelay: 1,
maxDelay: 8,
expBase: 2,
jitter: 1,
httpStatusCodes: [500, 503, 504],
},
},
});
try {
const response = await ai.models.generateContent({
model,
contents: "Responde con una frase breve de saludo.",
});
if (!response.text) {
console.error("Se recibió una respuesta sin texto; revisa sus metadatos.");
process.exitCode = 1;
} else {
console.log(response.text);
}
} catch (error) {
if (error instanceof ApiError) {
console.error(`La petición ha fallado. Código HTTP: ${error.status}`);
} else {
console.error("Fallo local o de conexión; revisa el diagnóstico interno.");
}
process.exitCode = 1;
}En ambos SDK, timeout se expresa en milisegundos, mientras que los campos de demora se expresan en segundos. attempts: 3 no significa tres reintentos adicionales. Los treinta segundos de timeout y los valores de espera son decisiones de este ejemplo, no límites ni recomendaciones universales de Google. Tampoco fijan un plazo total de treinta segundos para toda la operación con reintentos. Consulta las referencias de Python y JavaScript.
Los ejemplos se comprobaron localmente con google-genai 2.33.0 y @google/genai 2.31.0, claves ficticias y respuestas HTTP simuladas. Se verificaron el éxito tras un fallo transitorio, el máximo de intentos y la ausencia de reintentos para errores excluidos. No se hicieron llamadas reales a Gemini ni se comprobaron cuotas de una cuenta.
Si persisten los errores 500, 503 o 504
Un 500 puede justificar un reintento limitado. Si falla siempre la misma petición, compara una versión mínima con la original: retira opciones no imprescindibles o reduce la entrada conservando la tarea que quieres probar. Que la versión corta funcione aporta una pista, pero no demuestra por sí solo cuál es el límite interno del servicio.
Un 503 indica indisponibilidad del servicio. Consulta la página oficial de estado de Gemini y evita acumular trabajo contra un servicio que sigue fallando. Al agotar los intentos, devuelve un estado claro al usuario o deja el trabajo pendiente para una reanudación controlada. Una página de estado sin incidentes tampoco descarta un problema que afecte a tu petición.
Un 504 indica que se agotó un plazo de ejecución. Distingue el error recibido del servidor de un timeout del cliente. Aumentar el timeout local solo sirve si tu cliente estaba abandonando antes; no amplía automáticamente el plazo del servidor. Reduce o divide la tarea cuando puedas hacerlo sin perder su propósito. La guía oficial de solución de problemas detalla las comprobaciones por código.
Si tu cliente deja de esperar, no puedes concluir que el servidor no haya procesado la solicitud. Antes de repetir una operación que produzca efectos externos, comprueba cómo evitarás duplicados. Los ejemplos anteriores generan texto; no implementan una política de idempotencia para herramientas, pagos o escrituras externas.
Qué información conservar cuando necesitas ayuda
Cuando ya has corregido los datos evidentes y agotado los intentos previstos, deja de repetir la misma prueba. Prepara una reproducción mínima con el método, el modelo, la versión de API, el SDK y su versión, la hora del fallo, el estado HTTP y el mensaje depurado. Añade cuántas llamadas se enviaron realmente y si ocurre también con una entrada sencilla.
Para un 429, incluye la métrica y ventana que aparecen en el error, junto con el límite activo del proyecto. Para un 403, indica el tipo de restricción y si falla solo la inferencia o también otras operaciones. Comparte identificadores sensibles únicamente por un canal de soporte adecuado; nunca publiques claves ni documentos privados en un foro.
¿Google cobra las peticiones que fallan?
La FAQ de facturación indica que las peticiones fallidas con 400 o 500 no se cobran por tokens, aunque cuentan para la cuota. No extiendas esa afirmación a cualquier código, a un timeout local o a una generación repetida: son situaciones distintas.
¿Activar el pago elimina los errores 429?
No. Puede cambiar los límites disponibles y resolver determinados requisitos de acceso, pero siguen existiendo límites por proyecto, modelo y nivel, además de posibles restricciones de gasto. Antes de activar el pago, identifica el motivo del error y consulta los límites actuales y las condiciones de facturación. No hay un multiplicador universal ni una garantía de que desaparezcan los 429.
