Los errores de Nano Banana 2 como 429 RESOURCE_EXHAUSTED y 502 Bad Gateway afectan la API Gemini 3.1 Flash Image (gemini-3.1-flash-image-preview). El error 429 representa aproximadamente el 70% de todos los fallos y significa que has excedido tu límite de velocidad — espera 60 segundos para el reinicio de RPM o verifica tu cuota diaria que se reinicia a medianoche hora del Pacífico. El error 502 indica que los servidores de Google devolvieron una respuesta inválida y normalmente se resuelve en 5-15 minutos. Esta guía cubre todos los códigos de error de Nano Banana 2 con límites de velocidad verificados, ejemplos reales de respuestas de error y código listo para producción en Python y TypeScript.
¿Qué hace diferentes los errores de Nano Banana 2 respecto a Nano Banana Pro?
Si has estado depurando errores de Nano Banana siguiendo guías escritas para Nano Banana Pro, es posible que estés aplicando las soluciones incorrectas a tu problema. Nano Banana 2 (ID del modelo: gemini-3.1-flash-image-preview) y Nano Banana Pro (ID del modelo: gemini-3-pro-image-preview) son modelos fundamentalmente diferentes con estructuras de precios distintas, límites de velocidad diferentes y comportamientos de error particulares. Comprender estas diferencias es el primer paso para corregir tus errores correctamente y evitar perder tiempo en depuración innecesaria.
La diferencia más crítica es el precio. Nano Banana 2 cuesta $0.25 por millón de tokens de entrada y $60 por millón de tokens de salida para la generación de imágenes, mientras que Nano Banana Pro cobra $2.00 por millón de tokens de entrada y $120 por millón de tokens de salida (ai.google.dev/pricing, verificado el 2 de marzo de 2026). Esto significa que NB2 es entre un 50% y un 87% más económico que Pro por token, y una sola imagen de resolución 1K cuesta aproximadamente $0.067 con NB2 en comparación con $0.134 con Pro. Esta diferencia de precios importa para el manejo de errores porque las estrategias de reintento tienen diferentes implicaciones de costo dependiendo del modelo que utilices. Para una comparación detallada entre Nano Banana 2 y Pro, tenemos un artículo dedicado que cubre todas las diferencias técnicas.
La segunda diferencia crítica es que Nano Banana 2 está clasificado como un modelo "preview" (vista previa), lo que significa que opera bajo límites de velocidad más estrictos que los modelos establecidos. La documentación oficial de Google establece explícitamente que "los modelos experimentales y de vista previa tienen límites de velocidad más bajos" (ai.google.dev/docs/rate-limits, 2 de marzo de 2026). En la práctica, esto significa que tu cuenta de Nivel 1 podría manejar 10 RPM para la generación de imágenes con NB2 en comparación con límites potencialmente más altos para modelos que no son de vista previa. Tanto NB2 como Pro carecen de un nivel gratuito para la generación de imágenes — si ves RESOURCE_EXHAUSTED en una cuenta de nivel gratuito, el error te está indicando que la generación de imágenes simplemente no está disponible sin la facturación habilitada.
Un detalle técnico que sorprende a muchos desarrolladores es el requisito de thought_signature en conversaciones multiturn. Cuando utilizas Nano Banana 2 en un contexto conversacional donde el modelo genera tanto texto como imágenes a lo largo de múltiples turnos, debes incluir el thought_signature de la respuesta anterior en tu siguiente solicitud. No hacerlo resulta en un error 400 Bad Request que parece confuso si no conoces este requisito. Este comportamiento es idéntico tanto para NB2 como para Pro, pero dado que NB2 es más nuevo, menos tutoriales lo cubren adecuadamente.
Diagnostica tu error de Nano Banana 2 en 30 segundos
Antes de profundizar en soluciones detalladas, utiliza esta tabla de referencia rápida para asociar tu error exacto con la corrección adecuada. Todos los errores de Nano Banana 2 se clasifican en una de dos categorías: errores reintentables donde debes implementar lógica de reintento automático, y errores no reintentables donde necesitas corregir algo en tu solicitud antes de volver a intentar. Identificar a qué categoría pertenece tu error te ahorra tiempo al evitar que uses el enfoque incorrecto.
| Código HTTP | Tipo de error | Causa | ¿Reintentable? | Tiempo de recuperación |
|---|---|---|---|---|
| 429 | RESOURCE_EXHAUSTED | Límite de velocidad excedido (RPM/RPD/TPM/IPM) | Sí | 60s (RPM) o medianoche PT (RPD) |
| 502 | Bad Gateway | Fallo del servidor upstream de Google | Sí | 5-15 minutos |
| 503 | Service Unavailable | Servidor sobrecargado (horas pico) | Sí | 30-60 minutos |
| 500 | Internal Server Error | Fallo inesperado del servidor | Sí | Variable |
| 400 | Bad Request | Parámetros inválidos o thought_signature faltante | No | Corregir el payload de la solicitud |
| 403 | Forbidden | Clave API inválida o restricción de región | No | Corregir credenciales |
| 200 | IMAGE_SAFETY | Contenido filtrado por el sistema de seguridad | No | Reformular el prompt |
Lo más importante que debes comprender es que las solicitudes fallidas — aquellas que devuelven 429, 502 o 503 — no son facturadas por Google. Solo pagas por las generaciones de imágenes exitosas. Esto significa que implementar lógica de reintento no tiene riesgo de costo adicional, lo cual es un alivio significativo para los desarrolladores preocupados por que su presupuesto se descontrole durante escenarios de error. Si tu aplicación encuentra una ráfaga de errores 429 mientras reintenta, tu factura permanece exactamente igual que si esos reintentos nunca hubieran ocurrido. Para una visión más amplia del manejo de errores en todos los modelos Nano Banana, consulta nuestra guía completa de solución de errores de Nano Banana.
Solucionar el error 429 RESOURCE_EXHAUSTED — El error más común de Nano Banana 2
El error 429 RESOURCE_EXHAUSTED es con diferencia el error más común que encontrarás al usar Nano Banana 2, representando aproximadamente el 70% de todos los fallos de la API. Este error significa que has alcanzado una de las cuatro dimensiones de límite de velocidad que Google aplica a las solicitudes de generación de imágenes. Comprender qué límite específico has alcanzado es crucial porque cada uno tiene una estrategia de recuperación y un tiempo de espera diferente.
Cuando recibes un error 429, la API devuelve una respuesta JSON que tiene este aspecto:
json{ "error": { "code": 429, "message": "Resource has been exhausted (e.g. check quota).", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "RATE_LIMIT_EXCEEDED", "metadata": { "consumer": "projects/YOUR_PROJECT_ID", "quota_limit": "GenerateContentRequestsPerMinutePerProjectPerModel", "quota_limit_value": "10" } } ] } }
El campo metadata en la respuesta de error es tu herramienta de depuración más valiosa. El campo quota_limit te indica exactamente qué límite has excedido. Las cuatro dimensiones de límite de velocidad para la generación de imágenes con Nano Banana 2 son RPM (solicitudes por minuto), TPM (tokens por minuto), RPD (solicitudes por día) e IPM (imágenes por minuto). Cada dimensión opera de forma independiente, así que alcanzar una no afecta a las demás. Tu cuenta de Nivel 1 podría tener 10 RPM pero 1,000 RPD — una vez que uses tu asignación diaria, debes esperar hasta la medianoche hora del Pacífico para que el contador de RPD se reinicie, independientemente de cuántos RPM te queden disponibles.
La solución más rápida para errores 429 relacionados con RPM es simplemente esperar 60 segundos. El contador de RPM se reinicia en una ventana rodante de un minuto, así que después de 60 segundos sin solicitudes, toda tu cuota de RPM vuelve a estar disponible. Para los límites de RPD, sin embargo, la espera es mucho más larga — el contador se reinicia a medianoche hora del Pacífico (UTC-8 o UTC-7 durante el horario de verano). Si alcanzas tu límite de RPD a las 9 AM hora del Pacífico, estás viendo una espera de 15 horas a menos que actualices tu nivel.
Un error común es enviar solicitudes lo más rápido posible y confiar en la lógica de reintento para manejar los errores 429. Aunque esto técnicamente funciona porque las solicitudes fallidas no se facturan, es ineficiente y crea carga innecesaria en los servidores de Google. Un enfoque mejor es implementar limitación de velocidad proactiva de tu lado. Si sabes que tu límite de Nivel 1 es de 10 RPM, espacia tus solicitudes al menos 6 segundos para mantenerte por debajo del límite de forma segura. Esto elimina la mayoría de los errores 429 antes de que ocurran. Para estrategias específicas para manejar el error 429 de Nano Banana Pro, muchos de los mismos principios se aplican a NB2 con números de límite de velocidad ajustados.
Implementar retroceso exponencial es la solución estándar para cualquier error 429 restante. Comienza con un retraso de 1 segundo después del primer fallo, duplícalo para cada reintento subsiguiente (2s, 4s, 8s, 16s), y añade un pequeño jitter aleatorio para prevenir problemas de "estampida" cuando múltiples clientes reintentan simultáneamente. Limita tu retraso máximo de reintento a 60 segundos para límites relacionados con RPM, y considera abandonar después de 5-6 reintentos si el límite parece ser basado en RPD en lugar de RPM.
Solucionar el error 502 Bad Gateway y 503 Service Unavailable
El error 502 Bad Gateway y el error 503 Service Unavailable son errores del lado del servidor que indican problemas en la infraestructura de Google, no con tu solicitud. Estos errores son fundamentalmente diferentes del 429 porque no hay nada incorrecto con tu código ni con tu uso de límite de velocidad — los servidores de Google están devolviendo respuestas inválidas (502) o están demasiado sobrecargados para procesar tu solicitud (503). La respuesta correcta a ambos es paciencia y lógica de reintento sistemática.
Cuando encuentras un error 502 Bad Gateway, la respuesta típicamente se ve así:
json{ "error": { "code": 502, "message": "Bad Gateway", "status": "UNAVAILABLE" } }
Un error 502 significa que el proxy inverso o el balanceador de carga que está delante de la API Gemini de Google recibió una respuesta inválida del servidor upstream que maneja tu solicitud. Esto puede ocurrir durante despliegues de servidores, actualizaciones de infraestructura o problemas de red transitorios dentro de los centros de datos de Google. La clave es que los errores 502 son casi siempre temporales — típicamente se resuelven en 5 a 15 minutos sin que se requiera ninguna acción de tu parte. Si estás viendo errores 502 persistentes más allá de 30 minutos, verifica el Google Cloud Status Dashboard para cualquier incidente de servicio en curso que afecte la API Gemini.
El error 503 Service Unavailable sigue un patrón diferente. Mientras que los errores 502 son usualmente fallos transitorios breves, los errores 503 a menudo indican sobrecarga sostenida del servidor, lo cual es más común durante las horas de uso pico. Basándonos en informes de la comunidad y nuestras propias pruebas, las tasas de error pico para Nano Banana 2 tienden a concentrarse entre las 10:00 y las 14:00 UTC en días laborables, lo que corresponde a la superposición de la mañana estadounidense y la tarde europea. Si tu aplicación no es sensible al tiempo, programar solicitudes de generación de imágenes durante horas fuera de pico (temprano en la mañana UTC o fines de semana) puede reducir dramáticamente las tasas de error 503.
El cuerpo de respuesta del 503 es similar al 502 pero usualmente incluye información más específica sobre la capacidad del servidor:
json{ "error": { "code": 503, "message": "The model is overloaded. Please try again later.", "status": "UNAVAILABLE" } }
Para los usuarios de MCP (Model Context Protocol) que acceden a Nano Banana 2 a través de herramientas como Cherry Studio, Claude Code o Dify, estos errores del lado del servidor pueden aparecer de formas confusas porque la capa MCP añade su propio envoltorio de errores. Si ves errores como "upstream connection error" o "model not responding" en tu cliente MCP, la causa subyacente es probablemente un 502 o 503 de la API Gemini. La solución es la misma: esperar y reintentar. Los usuarios de Cherry Studio en particular deberían verificar sus logs del servidor (generalmente en ~/.cherry-studio/logs/) para ver el código de estado HTTP real de la API, lo que ayuda a distinguir entre problemas de la capa MCP y fallos reales de la API.
Tanto los errores 502 como los 503 deben manejarse con una estrategia de reintento que use retrasos iniciales más largos que los errores 429. Comienza con un retraso de 5 segundos para el primer reintento, aumenta a 15 segundos, luego a 30 segundos, y limita a 60 segundos. Dado que estos errores indican estrés del lado del servidor, reintentar agresivamente puede empeorar la situación. Permite un máximo de 3-4 reintentos antes de fallar graciosamente con un mensaje de error amigable para el usuario que sugiera intentar de nuevo en unos minutos.
Solucionar errores del cliente — 400 Bad Request, 403 Forbidden e IMAGE_SAFETY
Los errores del cliente son fundamentalmente diferentes de los errores del lado del servidor que cubrimos anteriormente porque indican un problema con tu solicitud que no se solucionará reintentando. Enviar la misma solicitud malformada cien veces te dará el mismo error cien veces. Necesitas identificar y corregir el problema en el payload de tu solicitud, las credenciales o el prompt antes de intentar de nuevo.
400 Bad Request es el error de cliente más variado porque cubre múltiples modos de fallo. La causa más común para Nano Banana 2 específicamente es el thought_signature faltante en conversaciones multiturn. Cuando NB2 devuelve una respuesta que incluye tokens de pensamiento (lo cual ocurre incluso si configuras la visibilidad del pensamiento en "off" — los tokens de pensamiento siempre se facturan independientemente de tu preferencia), la respuesta incluye un campo thought_signature que debes pasar de vuelta en tu siguiente solicitud dentro de la misma conversación. Así es como se ve el error cuando falta la firma:
json{ "error": { "code": 400, "message": "Request contains an invalid argument: thought_signature is required for multi-turn conversations with this model.", "status": "INVALID_ARGUMENT" } }
La solución es directa pero fácil de pasar por alto: extrae el thought_signature de la respuesta del modelo e inclúyelo en el generation_config de tu siguiente solicitud. Si estás usando un framework o SDK que gestiona el historial de conversación, asegúrate de que preserve este campo entre turnos. Muchos frameworks populares incluyendo LangChain y algunas implementaciones de servidores MCP todavía no manejan esto automáticamente, así que puede que necesites añadir lógica personalizada para extraer e inyectar la firma.
Otras causas del error 400 incluyen relaciones de aspecto inválidas (NB2 soporta relaciones específicas como 1:1, 3:4, 4:3, 9:16, 16:9, y otras — consulta la documentación oficial para la lista completa), solicitar tamaños de imagen no soportados, o enviar demasiadas imágenes de referencia. Nano Banana 2 soporta hasta 14 imágenes de referencia (10 objetos o 6 objetos más 5 personajes), y exceder este límite produce un error 400 con un mensaje descriptivo.
403 Forbidden típicamente significa una de tres cosas: tu clave API es inválida o fue revocada, tu proyecto de Google Cloud no tiene habilitada la API Gemini, o tu región geográfica tiene restricciones para acceder al servicio. La solución depende de la causa específica. Primero, verifica que tu clave API sea correcta probándola con una solicitud de solo texto (que no requiere facturación). Si las solicitudes de texto funcionan pero la generación de imágenes falla, probablemente necesitas habilitar la facturación en tu proyecto — recuerda, Nano Banana 2 no tiene nivel gratuito para la generación de imágenes.
Los bloqueos de IMAGE_SAFETY son una categoría especial. Estos no son errores HTTP en el sentido tradicional — la API devuelve un código de estado 200 OK, pero el cuerpo de la respuesta indica que la imagen generada fue bloqueada por los filtros de seguridad de Google. La respuesta se ve así:
json{ "candidates": [ { "finishReason": "IMAGE_SAFETY", "safetyRatings": [ { "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "probability": "HIGH", "blocked": true } ] } ] }
Cuando esto ocurre, el modelo intentó generar una imagen pero la salida fue marcada antes de la entrega. No se te factura por las generaciones bloqueadas por seguridad. Para resolver esto, reformula tu prompt para evitar contenido que active los filtros de seguridad. Añadir guía de estilo explícita como "fotografía profesional", "estilo editorial" o "ilustración limpia" puede ayudar a dirigir al modelo lejos de contenido que podría ser marcado. Evita el lenguaje ambiguo que pueda interpretarse de múltiples maneras, ya que el sistema de seguridad peca de precavido.
Límites de velocidad de Nano Banana 2 explicados — Cada nivel y límite
Comprender el sistema completo de límites de velocidad es esencial para prevenir errores antes de que ocurran. Google estructura los límites de velocidad de Nano Banana 2 en cuatro dimensiones y cuatro niveles, y cada combinación tiene un límite numérico específico que determina cuántas solicitudes puede hacer tu proyecto. Todos estos datos fueron verificados directamente desde ai.google.dev/gemini-api/docs/rate-limits el 2 de marzo de 2026. Para un desglose completo de todos los modelos Gemini, consulta nuestro desglose completo de límites de velocidad de la API Gemini por nivel.
Las cuatro dimensiones de límite de velocidad funcionan de forma independiente. RPM (solicitudes por minuto) limita el número de llamadas a la API independientemente de su tamaño. TPM (tokens por minuto) limita el rendimiento total de tokens en todas las solicitudes. RPD (solicitudes por día) establece un techo diario que se reinicia a medianoche hora del Pacífico. IPM (imágenes por minuto) limita específicamente la salida de generación de imágenes. Puedes alcanzar cualquiera de estos límites sin afectar a los demás — por ejemplo, podrías tener capacidad RPM restante pero haber agotado tu cuota de IPM del minuto.
Los límites de velocidad se aplican por proyecto de Google Cloud, no por clave API. Esta es una distinción crucial que muchos desarrolladores pasan por alto. Si creas múltiples claves API bajo el mismo proyecto esperando multiplicar tus límites de velocidad, no funcionará. Todas las claves bajo un mismo proyecto comparten el mismo pool de límites de velocidad. Para aumentar genuinamente tu límite de velocidad efectivo, necesitarías crear proyectos de Google Cloud separados, pero este enfoque tiene sus propias complicaciones con la gestión de facturación y generalmente no se recomienda a menos que tengas una razón arquitectónica específica.
El sistema de niveles de Google progresa desde Gratuito pasando por Nivel 1, Nivel 2 y Nivel 3. El nivel gratuito no soporta la generación de imágenes con Nano Banana 2 en absoluto — recibirás un error 429 inmediatamente si intentas generar imágenes sin la facturación habilitada. El Nivel 1 se activa cuando habilitas la facturación y proporciona los límites base de generación de imágenes. El Nivel 2 requiere $250 o más en gasto acumulado durante los últimos 30 días, y el Nivel 3 requiere $1,000 o más. Cada actualización de nivel trae límites significativamente más altos en las cuatro dimensiones.
Para las cuentas de Nivel 1, la implicación práctica es que puedes generar aproximadamente 10 imágenes por minuto y hasta 1,000 por día. Si tu aplicación procesa solicitudes de usuarios en tiempo real, esto significa que puedes manejar aproximadamente una solicitud de imagen cada 6 segundos de forma sostenida, o ráfagas breves de hasta 10 solicitudes simultáneas seguidas de un período de enfriamiento obligatorio. Para aplicaciones que procesan imágenes por lotes (como generar catálogos de productos o contenido para redes sociales), el límite de RPD de 1,000 por día suele ser la restricción vinculante en lugar de RPM.
La API por lotes ofrece una alternativa para cargas de trabajo de alto volumen. Nano Banana 2 soporta procesamiento por lotes con límites de cola de 1 millón de tokens (Nivel 1), 250 millones de tokens (Nivel 2) y 750 millones de tokens (Nivel 3). Las solicitudes por lotes se procesan de forma asíncrona con menor prioridad pero no están sujetas a los mismos límites de RPM que las solicitudes síncronas. Si tu caso de uso no requiere generación de imágenes en tiempo real, la API por lotes puede aumentar dramáticamente tu rendimiento sin requerir una actualización de nivel. Servicios como laozhang.ai proporcionan acceso a Nano Banana 2 con límites de velocidad relajados a aproximadamente $0.05 por imagen, lo cual puede ser una alternativa práctica para desarrolladores que necesitan mayor rendimiento sin la complejidad de gestionar múltiples proyectos de Google Cloud o esperar actualizaciones de nivel.
Código de manejo de errores listo para producción para Nano Banana 2
Implementar un manejo robusto de errores requiere más que simplemente envolver las llamadas a la API en bloques try-catch. Una solución lista para producción debe incluir retroceso exponencial con jitter, patrones de circuit breaker para evitar golpear un servicio que está fallando, y cola de solicitudes para mantenerse dentro de los límites de velocidad de forma proactiva. A continuación se presentan implementaciones completas en Python y TypeScript que puedes adaptar para tu integración con Nano Banana 2.
Implementación en Python
pythonimport time import random import google.generativeai as genai from collections import deque from threading import Lock class NanoBanana2Client: """Production error handler for Nano Banana 2 (gemini-3.1-flash-image-preview)""" MODEL_ID = "gemini-3.1-flash-image-preview" def __init__(self, api_key: str, max_rpm: int = 10): genai.configure(api_key=api_key) self.model = genai.GenerativeModel(self.MODEL_ID) self.max_rpm = max_rpm self.request_timestamps = deque() self.lock = Lock() self.circuit_open = False self.circuit_failures = 0 self.circuit_threshold = 5 self.circuit_reset_time = 0 def _wait_for_rate_limit(self): """Proactive rate limiting - prevent 429 before it happens""" with self.lock: now = time.time() # Remove timestamps older than 60 seconds while self.request_timestamps and self.request_timestamps[0] < now - 60: self.request_timestamps.popleft() if len(self.request_timestamps) >= self.max_rpm: wait_time = 60 - (now - self.request_timestamps[0]) + 0.1 if wait_time > 0: time.sleep(wait_time) self.request_timestamps.append(time.time()) def _check_circuit_breaker(self): """Circuit breaker - stop hammering a failing service""" if self.circuit_open: if time.time() > self.circuit_reset_time: self.circuit_open = False self.circuit_failures = 0 else: raise Exception( f"Circuit breaker open. Retry after " f"{int(self.circuit_reset_time - time.time())}s" ) def generate_image(self, prompt: str, max_retries: int = 5, **kwargs): """Generate image with full error handling""" self._check_circuit_breaker() self._wait_for_rate_limit() for attempt in range(max_retries): try: response = self.model.generate_content( prompt, generation_config=genai.types.GenerationConfig( response_mime_type="image/png", **kwargs ) ) # Check for IMAGE_SAFETY block if hasattr(response, 'candidates') and response.candidates: candidate = response.candidates[0] if hasattr(candidate, 'finish_reason'): if candidate.finish_reason.name == "IMAGE_SAFETY": return {"error": "IMAGE_SAFETY", "retryable": False, "message": "Content blocked by safety filter"} # Success - reset circuit breaker self.circuit_failures = 0 return {"success": True, "response": response} except Exception as e: error_code = getattr(e, 'code', None) or self._extract_code(str(e)) if error_code == 429: # Rate limit - exponential backoff with jitter delay = min(60, (2 ** attempt) + random.uniform(0, 1)) time.sleep(delay) continue elif error_code in (502, 503): # Server error - longer backoff self.circuit_failures += 1 if self.circuit_failures >= self.circuit_threshold: self.circuit_open = True self.circuit_reset_time = time.time() + 120 delay = min(60, 5 * (2 ** attempt) + random.uniform(0, 2)) time.sleep(delay) continue elif error_code in (400, 403): # Client error - do not retry return {"error": error_code, "retryable": False, "message": str(e)} else: # Unknown error return {"error": "UNKNOWN", "retryable": False, "message": str(e)} return {"error": "MAX_RETRIES", "retryable": True, "message": f"Failed after {max_retries} attempts"} def _extract_code(self, error_str: str) -> int: for code in [429, 502, 503, 500, 400, 403]: if str(code) in error_str: return code return 0
Implementación en TypeScript / Node.js
typescriptimport { GoogleGenerativeAI } from "@google/generative-ai"; interface GenerationResult { success: boolean; response?: any; error?: string; retryable?: boolean; message?: string; } class NanoBanana2Client { private static MODEL_ID = "gemini-3.1-flash-image-preview"; private model: any; private requestTimestamps: number[] = []; private maxRpm: number; private circuitOpen = false; private circuitFailures = 0; private circuitThreshold = 5; private circuitResetTime = 0; constructor(apiKey: string, maxRpm = 10) { const genAI = new GoogleGenerativeAI(apiKey); this.model = genAI.getGenerativeModel({ model: NanoBanana2Client.MODEL_ID }); this.maxRpm = maxRpm; } private async waitForRateLimit(): Promise<void> { const now = Date.now(); this.requestTimestamps = this.requestTimestamps .filter(ts => ts > now - 60000); if (this.requestTimestamps.length >= this.maxRpm) { const waitMs = 60000 - (now - this.requestTimestamps[0]) + 100; if (waitMs > 0) await this.sleep(waitMs); } this.requestTimestamps.push(Date.now()); } async generateImage( prompt: string, maxRetries = 5 ): Promise<GenerationResult> { if (this.circuitOpen) { if (Date.now() > this.circuitResetTime) { this.circuitOpen = false; this.circuitFailures = 0; } else { const waitSec = Math.ceil( (this.circuitResetTime - Date.now()) / 1000 ); return { success: false, error: "CIRCUIT_OPEN", retryable: true, message: `Circuit breaker open. Retry in ${waitSec}s` }; } } await this.waitForRateLimit(); for (let attempt = 0; attempt < maxRetries; attempt++) { try { const result = await this.model.generateContent({ contents: [{ role: "user", parts: [{ text: prompt }] }], generationConfig: { responseMimeType: "image/png" }, }); const candidate = result.response?.candidates?.[0]; if (candidate?.finishReason === "IMAGE_SAFETY") { return { success: false, error: "IMAGE_SAFETY", retryable: false, message: "Content blocked by safety filter" }; } this.circuitFailures = 0; return { success: true, response: result.response }; } catch (err: any) { const code = err?.status || err?.code || this.extractCode(err.message); if (code === 429) { const delay = Math.min(60000, (2 ** attempt) * 1000 + Math.random() * 1000); await this.sleep(delay); continue; } if (code === 502 || code === 503) { this.circuitFailures++; if (this.circuitFailures >= this.circuitThreshold) { this.circuitOpen = true; this.circuitResetTime = Date.now() + 120000; } const delay = Math.min(60000, 5000 * (2 ** attempt) + Math.random() * 2000); await this.sleep(delay); continue; } if (code === 400 || code === 403) { return { success: false, error: String(code), retryable: false, message: err.message }; } return { success: false, error: "UNKNOWN", retryable: false, message: err.message }; } } return { success: false, error: "MAX_RETRIES", retryable: true, message: `Failed after ${maxRetries} attempts` }; } private sleep(ms: number): Promise<void> { return new Promise(resolve => setTimeout(resolve, ms)); } private extractCode(msg: string): number { for (const code of [429, 502, 503, 500, 400, 403]) { if (msg?.includes(String(code))) return code; } return 0; } }
Ambas implementaciones comparten tres patrones arquitectónicos clave que las hacen listas para producción. Primero, la limitación proactiva de velocidad rastrea las marcas de tiempo de las solicitudes y retrasa nuevas solicitudes antes de que alcancen los límites de velocidad de Google, previniendo la mayoría de los errores 429 antes de que ocurran. Segundo, el patrón de circuit breaker detecta cuando el servidor está en un estado degradado (después de 5 fallos consecutivos) y temporalmente deja de enviar solicitudes durante 2 minutos, dando al servidor tiempo para recuperarse en lugar de empeorar la sobrecarga. Tercero, la estrategia de retroceso exponencial con jitter utiliza retrasos progresivamente más largos entre reintentos mientras añade aleatoriedad para prevenir que múltiples clientes reintentem al unísono.
Cuando los errores persisten — Alternativas y optimización de costos
Si has implementado todas las estrategias de manejo de errores anteriores y sigues alcanzando los límites de velocidad regularmente, el problema es probablemente arquitectónico más que técnico. Has superado la capacidad del nivel actual, y hay tres caminos prácticos hacia adelante: actualizar tu nivel de Google Cloud, optimizar tus patrones de solicitud, o usar un servicio proxy de API que proporcione límites más altos.
Actualizar tu nivel es la solución más directa pero requiere cumplir con los umbrales de gasto de Google. Pasar del Nivel 1 al Nivel 2 requiere $250 en gasto acumulado de API durante 30 días, lo que triplica tu RPM de 10 a 30 y quintuplica tu RPD de 1,000 a 5,000. Para muchas aplicaciones en producción, los límites del Nivel 2 son suficientes. El Nivel 3 ($1,000+ de gasto en 30 días) duplica todo nuevamente a 60 RPM y 10,000 RPD, lo que maneja cargas de trabajo sustanciales. La transición es automática una vez que cumples el umbral de gasto — no hay proceso de solicitud ni aprobación manual necesaria.
Optimizar tus patrones de solicitud puede a menudo retrasar o eliminar la necesidad de una actualización de nivel. Considera implementar una cola de solicitudes que agrupe trabajos de generación de imágenes y los procese a un ritmo constante justo por debajo de tu límite de RPM. Cachea las imágenes generadas para que nunca generes la misma imagen dos veces para el mismo prompt. Usa la API por lotes para cargas de trabajo que no son sensibles al tiempo, la cual opera fuera de los límites estándar de RPM. Y si estás generando imágenes en múltiples resoluciones, comienza con 512px ($0.045 por imagen) para vistas previas y solo genera resoluciones más altas para selecciones confirmadas.
Los servicios proxy de API ofrecen un tercer camino que combina límites de velocidad más altos con potenciales ahorros de costos. Servicios como laozhang.ai proporcionan acceso a Nano Banana 2 a aproximadamente $0.05 por imagen sin restricciones de límite de velocidad, lo cual es competitivo con los precios directos de Google en el nivel de resolución 1K ($0.067) y significativamente más económico que resoluciones superiores. Para las alternativas más económicas de API Nano Banana 2, tenemos una comparación dedicada que cubre todos los proveedores principales. La contrapartida es que los servicios proxy añaden un salto de red y una dependencia de un proveedor externo, así que funcionan mejor para cargas de trabajo no críticas o como respaldo cuando tu cuota principal de Google Cloud se agota.
Aquí tienes una comparación práctica de costos para generar 1,000 imágenes a resolución 1K por día:
| Proveedor | Costo por imagen | Costo diario (1K imágenes) | Límite de velocidad | Ideal para |
|---|---|---|---|---|
| Google Directo (Nivel 1) | $0.067 | $67.00 | 10 RPM / 1,000 RPD | Desarrollo, bajo volumen |
| Google Directo (Nivel 2) | $0.067 | $67.00 | 30 RPM / 5,000 RPD | Producción, volumen medio |
| Google Directo (Nivel 3) | $0.067 | $67.00 | 60 RPM / 10,000 RPD | Empresarial, alto volumen |
| laozhang.ai | ~$0.05 | ~$50.00 | Sin límite estricto de RPM | Sensible al costo, alto volumen |
Los precios de Google son los mismos en todos los niveles — los niveles solo afectan los límites de velocidad, no el costo por imagen. Esto significa que la propuesta de valor de una actualización de nivel es puramente sobre capacidad de rendimiento, no sobre economía unitaria. Si el costo es tu principal preocupación y te sientes cómodo con un servicio proxy, puedes ahorrar aproximadamente un 25% por imagen mientras obtienes límites de velocidad efectivamente ilimitados. La documentación está disponible en docs.laozhang.ai y puedes probar la generación de imágenes en images.laozhang.ai.
Preguntas frecuentes
¿Cómo soluciono el error 429 en Nano Banana 2?
El error 429 RESOURCE_EXHAUSTED significa que has excedido uno de los cuatro límites de velocidad: RPM (solicitudes por minuto), TPM (tokens por minuto), RPD (solicitudes por día) o IPM (imágenes por minuto). La solución más rápida para los límites de RPM es esperar 60 segundos. Para los límites de RPD, debes esperar hasta la medianoche hora del Pacífico. Implementa retroceso exponencial en tu código comenzando con un retraso de 1 segundo, duplicando cada reintento hasta un máximo de 60 segundos. Espacia proactivamente tus solicitudes para mantenerte por debajo del límite — para cuentas de Nivel 1, esto significa no más de 10 solicitudes por minuto para generación de imágenes.
¿Cuáles son los límites de velocidad de Nano Banana 2?
Los límites de velocidad de Nano Banana 2 (gemini-3.1-flash-image-preview) varían según el nivel. El Nivel 1 (facturación habilitada) permite 10 RPM, 4M TPM, 1,000 RPD y 10 IPM para generación de imágenes. El Nivel 2 ($250+ de gasto en 30 días) permite 30 RPM, 10M TPM, 5,000 RPD y 30 IPM. El Nivel 3 ($1,000+ de gasto) permite 60 RPM, 20M TPM, 10,000 RPD y 60 IPM. El nivel gratuito no soporta la generación de imágenes. Estos límites son por proyecto, no por clave API, y fueron verificados desde ai.google.dev el 2 de marzo de 2026.
¿Por qué Nano Banana 2 sigue dando errores 502?
El error 502 Bad Gateway indica un problema en los servidores de Google, no con tu código. Estos errores típicamente se resuelven en 5-15 minutos. Son más comunes durante las horas de uso pico (10:00-14:00 UTC). Implementa lógica de reintento con un retraso inicial de 5 segundos, aumentando a 30-60 segundos. Si los errores 502 persisten más allá de 30 minutos, verifica el Google Cloud Status Dashboard para incidentes de servicio. No se te factura por solicitudes fallidas con error 502.
¿Es Nano Banana 2 gratuito de usar?
Las solicitudes de solo texto de Nano Banana 2 están disponibles en el nivel gratuito, pero la generación de imágenes requiere tener la facturación habilitada (Nivel 1 o superior). No existe un nivel gratuito para la generación de imágenes con NB2. Los costos por imagen van desde $0.045 (512px) hasta $0.151 (resolución 4K). Los tokens de entrada cuestan $0.25 por millón y los tokens de salida de imagen cuestan $60 por millón, según lo verificado en la página oficial de precios de Google el 2 de marzo de 2026.
¿Qué es el error de thought_signature en Nano Banana 2?
El error de thought_signature (400 Bad Request) ocurre en conversaciones multiturn cuando no incluyes el thought_signature de la respuesta anterior del modelo. Incluso si configuras la visibilidad del pensamiento en "off", NB2 sigue generando tokens de pensamiento e incluye una firma que debe pasarse de vuelta en los turnos subsiguientes. Extrae el campo thought_signature de la respuesta de la API e inclúyelo en el generation_config de tu siguiente solicitud para resolver este error.
¿Cómo se compara Nano Banana 2 con Pro en cuanto a errores?
Nano Banana 2 y Pro comparten los mismos códigos de error (429, 502, 503, 400, 403, IMAGE_SAFETY) pero difieren en límites de velocidad y precios. NB2 es entre un 50% y un 87% más económico por token pero opera bajo límites de velocidad más estrictos como modelo de vista previa. La entrada de NB2 cuesta $0.25/1M tokens frente a $2.00/1M de Pro, y la salida de NB2 cuesta $60/1M frente a $120/1M de Pro. Ambos carecen de generación de imágenes en nivel gratuito. En cuanto a resiliencia ante errores, Pro puede tener límites ligeramente más generosos en el mismo nivel debido a su estatus de modelo no preview.