Cuando Nano Banana API falla, la primera decisión no es reintentar, cambiar la key, cambiar el modelo ni salir a otro proveedor. Primero separa la rama del fallo. 429 RESOURCE_EXHAUSTED apunta a cuota o rate limit. 503 UNAVAILABLE empieza como capacidad o disponibilidad temporal. 504 DEADLINE_EXCEEDED pertenece al timeout. Una respuesta HTTP correcta sin imagen exige revisar parts, inlineData, modalidad de salida, safety finish y referencias de archivo. Request denied puede venir de permisos, safety, key/proyecto, file resource o gateway.
| Lo que ves | Primera comprobación segura | Siguiente paso |
|---|---|---|
429 RESOURCE_EXHAUSTED | Mira los límites reales del proyecto y del modelo. | Backoff con jitter, cola, Batch API o ruta específica de 429. |
503 UNAVAILABLE / 504 DEADLINE_EXCEEDED | Repite la misma ruta: modelo, endpoint, proyecto, key, payload e input. | Para 503, retry acotado o cola; para 504, timeout o menor carga. |
| Sin imagen o solo texto | Recorre todos los response parts y busca datos de imagen. | Corrige parser, modality, safety o file reference. |
| Request denied | Separa 403, blocked key, safety finish, file resource y gateway denial. | Corrige solo el owner que rechazó la solicitud. |
Límite factual: la documentación de Google Gemini API sobre troubleshooting, image generation, rate limits, Batch API y Files API se revisó el 19 de abril de 2026. No se usan tablas antiguas de cuota, porcentajes de incidentes, ventanas horarias prometidas ni frases de arreglo garantizado.
429 RESOURCE_EXHAUSTED apunta primero a cuota
429 RESOURCE_EXHAUSTED no demuestra que el modelo esté roto. Primero significa presión de cuota o rate limit. En Gemini API los límites suelen aplicar a nivel de proyecto, así que cambiar a otra key dentro del mismo proyecto puede dejarte en el mismo techo.
El orden correcto es: comprobar límites vivos del proyecto, confirmar el modelo y tier, y después aplicar backoff con jitter y límite de intentos. Las tareas no urgentes deberían pasar a cola o Batch API para no competir con llamadas interactivas.
Si 429 aparece en sesiones normales, ya no es un simple pico. Es planificación de capacidad. La rama exacta está en Gemini Image 429 rate limit; la arquitectura amplia de límites está en Gemini API rate limits.
503 y 504 no se recuperan igual
503 UNAVAILABLE indica disponibilidad temporal o capacidad. No prueba que billing, key o prompt sean la causa. Repite la misma ruta sin tocar variables. Si sigue 503, conserva la rama de capacidad. Si pasa a 429, cambia a cuota. Si pasa a 400/403, deja de tratarlo como sobrecarga.
504 DEADLINE_EXCEEDED es timeout. Puede venir de input pesado, generación compleja, timeout de cliente demasiado corto o backend lento. Para 504 suele servir más subir el timeout o reducir la carga que reintentar rápido.
Cuando 503/504 se mantienen, mueve el caso a Gemini 3 Pro Image 503 overloaded, donde la recuperación se centra en capacidad y timeout sin mezclar credenciales.
Sin imagen empieza en los response parts
Una respuesta HTTP correcta puede no incluir imagen utilizable. En Gemini image generation la salida de imagen vive dentro de parts; una aplicación que solo lee texto o un campo fijo puede mostrar “sin imagen” aunque el problema real sea el parser.
Recorre candidates y parts, busca inlineData con MIME type de imagen y guarda solo image parts reales. Si no aparece, revisa si la solicitud pidió imagen, si hubo safety finish, si el archivo de entrada era un recurso accesible por la API y si un gateway transformó la respuesta.
No declares caída del servicio antes de esa inspección. Muchas veces la reparación es pedir output de imagen explícitamente, corregir el loop de parts o subir el archivo como recurso válido.
Request denied es una división, no un diagnóstico
Request denied puede pertenecer a varias capas. 403 PERMISSION_DENIED se resuelve en key, proyecto, API habilitada o permisos. finishReason: SAFETY es una rama de seguridad, aunque el texto de la aplicación parezca una denegación. Un file URI inválido o de otro proyecto puede verse como rechazo desde la app. Un gateway puede aplicar su propia política antes de llegar a Google.
Registra por separado HTTP status, status string, finish reason, respuesta upstream y respuesta del gateway. Si Google devuelve 403, corrige permisos. Si el gateway rechaza, corrige auth o policy del gateway. Si safety corta la salida, cambia prompt o ruta. Si el archivo no es accesible, corrige el recurso.
La repetición por la misma ruta conserva la señal
La repetición por la misma ruta mantiene constantes modelo, endpoint, proyecto, key, payload, input asset y formato. Así sabes si la rama se mantiene o cambia.
| Resultado de la repetición | Qué significa | Acción |
|---|---|---|
| Sigue 429 | Rama de cuota estable | Backoff, cola, Batch API o ruta 429 |
| Sigue 503 | Rama de capacidad estable | Retry acotado, cola o ruta 503 |
| Cambia a 504 | Aparece timeout | Subir timeout o reducir carga |
| Éxito sin imagen | Aparece response shape | Revisar parts, inlineData, modality, safety, file |
| Cambia a 403 o denial | Aparecen permisos, safety o file | Corregir el owner concreto |
Después de probar la rama, cambia una variable cada vez. Si el problema persistente es cuota, evalúa Nano Banana 2 alternative 429 para decidir entre cola, batch o ruta alternativa.
Preguntas frecuentes
¿503 significa que Nano Banana API está caído?
No necesariamente. Un 503 muestra que la ruta actual entró en capacidad o disponibilidad temporal. Repite la misma ruta y compara con otros modelos o endpoints antes de concluir algo más amplio.
¿Activar billing arregla 503?
Billing puede cambiar cuotas y tier, pero no arregla automáticamente una rama 503 demostrada. Cuota es 429; capacidad es 503.
¿Por qué recibo texto pero no imagen?
El parser puede estar mirando el campo equivocado, la solicitud quizá no pidió salida de imagen, la generación pudo terminar por safety, o el archivo de entrada no era accesible para la API.
¿Qué revisar primero con request denied?
Primero HTTP status. Para 403 revisa key, proyecto, API habilitada y permisos. Si hay safety finish, trabaja la rama safety. Si hay archivos, revisa URI, MIME type, state y ownership.
¿Cuándo cambiar modelo o proveedor?
Después de demostrar la rama. Cuota persistente, capacidad persistente, límite safety o policy de gateway pueden justificar una ruta diferente, pero no cambies todo al inicio.