Cuando Nano Banana Pro devuelve HTTP 503 UNAVAILABLE, la regla más útil es confiar antes en el code y en el status que en el message string. Eso importa porque gemini-3-pro-image-preview puede devolver un 503 UNAVAILABLE real incluso cuando el texto dice Deadline expired before operation could complete. La frase suena a timeout, pero eso no convierte el caso en 504 por sí solo.
Aquí es donde muchas páginas de troubleshooting pierden valor. Algunas solo dicen "503 = overloaded, vuelve a intentar". Otras ven deadline y mandan al lector demasiado pronto a timeout tuning. Pero en este exact symptom el primer trabajo de la página es otro: decidir rápido si toca retry, tocar timeout o salir de la página 503 por completo.
Volví a revisar el Gemini API troubleshooting guide, las Gemini image generation docs y el hilo oficial del foro con el exact match 503 + Deadline expired el 15 de abril de 2026. La lectura práctica sigue siendo esta:
- si la respuesta sigue siendo
503 UNAVAILABLE, trátala primero como un fallo temporal de capacity y prueba bounded backoff en el mismo path; - si la respuesta es realmente
504 DEADLINE_EXCEEDED, o tu client hace timeout antes que el servidor, ahí sí toca timeout tuning y/o bajar la carga del request; - si el error en realidad es
429,400o403, no te quedes en esta página.
También hay una regla de verificación igual de importante: mantente en el same request path mientras diagnosticas. Si cambias model, prompt, SDK surface, auth owner y payload shape al mismo tiempo, luego no sabrás si el servicio se recuperó solo o si cambiaste la naturaleza del problema.
En 30 segundos: 503 o 504
La forma más estable de leer este fallo es con tres ramas:
503 UNAVAILABLE: pérdida temporal de capacity. Primero retry.504 DEADLINE_EXCEEDED: mismatch de timeout budget. Primero timeout o carga.429,400,403: esta página ya no es la correcta.
No es una heurística improvisada. La documentación actual de Google sigue separando 503 UNAVAILABLE de 504 DEADLINE_EXCEEDED, y para Nano Banana Pro ese split sigue siendo la forma más segura de empezar. El wording del message sirve para reconocer el síntoma, pero no debe mandar por encima de la clase real de la respuesta.
Si solo quieres un test mínimo y útil, haz esto: lee el HTTP code, confirma el status, vuelve a probar una vez en el mismo path y mira si la rama sigue siendo 503, si cambia a 504 o si se convierte en otra clase de error. Ese retest corto vale más que una teoría larga.
Por qué 503 puede decir Deadline expired
La parte confusa es que el texto del error parece un diagnóstico de timeout ya cerrado. Por eso mucha gente busca la frase literal antes que la clase de la respuesta. Pero aquí el dato importante es que el foro oficial ya mostró un ejemplo exacto donde 503 UNAVAILABLE y Deadline expired before operation could complete aparecieron juntos en el endpoint de imagen.
La conclusión práctica es sencilla. Usa la frase como puente de orientación, no como diagnóstico final. Sirve para que el lector confirme que está en la página correcta. No sirve para saltarse la comprobación de code y status.
Esta diferencia importa porque el primer movimiento cambia. Un 503 real sigue siendo una rama de capacidad temporal. Un 504 real es una rama de timeout budget y request load. Si saltas de la frase al timeout tuning demasiado pronto, puedes perder tiempo tocando la variable equivocada mientras el 503 se habría resuelto con un retry acotado.
Qué hacer si es un 503 real de capacity
Mientras la respuesta siga siendo 503 UNAVAILABLE, la mejor jugada no es rehacer toda tu integración. Es hacer la acción mínima que pueda confirmar recovery.
Lo más útil suele ser bounded backoff en el mismo path. En la práctica significa mantener el mismo model, la misma route, el mismo auth owner y una forma de request parecida mientras repites el intento. No hace falta reescribir el prompt, cambiar el SDK o mover el timeout antes de probar si la rama se recupera sola.
El ritmo puede ser muy simple:
- Espera un poco y reprueba una vez.
- Si sigue en 503, sube un poco la espera y vuelve a intentar.
- Cuando llegues a un número acotado de intentos, decide si toca esperar más, encolar el trabajo o usar un fallback temporal.
Lo de "acotado" importa porque un retry loop infinito esconde el momento en que ya deberías cambiar de estrategia. El bounded retry, en cambio, te deja ver si estás ante un wobble corto de capacity o ante un problema que ya pide queueing o una ruta alternativa.
También conviene evitar una confusión común: leer 503 como si fuera un problema de cuota personal. Mientras la rama siga siendo 503, subir billing o tocar throttling del lado del cliente no es el primer movimiento. Cuando el error cambie a 429 RESOURCE_EXHAUSTED, ahí sí toca ir a la rama de rate limits. Para eso tenemos la guía de Gemini API rate limits.
Qué hacer si en realidad es un 504 o un client timeout
La rama de timeout empieza cuando la respuesta ya es 504 DEADLINE_EXCEEDED o cuando tu propio client deja de esperar antes que el servidor. Solo ahí el timeout tuning pasa a ser la primera acción razonable.
En ese punto ya no estás resolviendo el mismo problema. No es "al servicio le falta capacity por ahora". Es "el timeout budget y la carga del request no encajan". Y por eso los movimientos cambian.
Las acciones iniciales más seguras suelen ser estas:
- subir el timeout del cliente a un valor razonable,
- reducir un poco la carga del request,
- y volver a probar el mismo path sin cambiar variables irrelevantes.
"Reducir la carga" no significa rehacer toda la arquitectura. Muchas veces basta con probar una variante un poco más ligera del mismo request para confirmar que la restricción real es de tiempo. El objetivo no es degradar la calidad para siempre, sino demostrar correctamente la timeout branch.
La advertencia clave es no reciclar consejo de timeout para cada mensaje que contenga la palabra deadline. El valor de esta página está precisamente en separar el wording tipo timeout de una timeout branch real.
Verifica en el mismo path y luego haz route-out limpio
Este paso es lo que convierte la página en una guía de recovery y no en una explicación correcta pero demasiado genérica.
En el retest de verificación intenta mantener el mismo model, la misma route, el mismo auth owner, la misma SDK surface y una forma de payload parecida. Si cambias model, prompt y timeout al mismo tiempo, el éxito ya no te dice qué fue lo que realmente funcionó.
Después del retest solo importan tres outcomes:
-
Sigue siendo
503 UNAVAILABLE.
Te quedas en la rama 503 y decides entre bounded retry, queueing o fallback deliberado. -
Se convierte en
504 DEADLINE_EXCEEDED, o tu client vuelve a hacer timeout.
Te mueves a la rama de timeout. -
Cambia a
429,400o403.
Esta exact 503 page terminó su trabajo y debes salir a la guía correcta.
La fuerza de una exact-error page está en ser estrecha. No en querer cubrir todo, sino en saber cuándo la rama ya cambió y toca handoff.
FAQ
¿Si veo Deadline expired, debo subir timeout de inmediato?
No. Solo cuando la respuesta es realmente 504 DEADLINE_EXCEEDED o hay un client timeout confirmado. Si la respuesta sigue siendo 503 UNAVAILABLE, tu primera rama sigue siendo 503.
¿Por qué 503 puede decir Deadline expired before operation could complete?
Porque el message string no equivale al diagnóstico completo. Ese exact combination ya apareció en el foro oficial, así que la frase sirve para reconocer el síntoma, pero no para anular el split por code/status.
¿Esto es lo mismo que quota o rate limit?
Normalmente no. La rama de quota o rate limit es 429 RESOURCE_EXHAUSTED, no 503 UNAVAILABLE. Si tu respuesta ya es 429, toca salir de esta página.
¿Conviene cambiar model, prompt y timeout al mismo tiempo?
No. Primero prueba la rama en el same path. Cambiar demasiadas variables a la vez destruye la señal de diagnóstico.
¿Cuándo debo dejar de usar esta página?
En cuanto la respuesta pase a ser un 504 real, un client timeout o una clase distinta como 429 / 400 / 403. Una exact-error page vale porque no se expande sin control.
La regla que sí conviene recordar
Cuando Nano Banana Pro devuelve 503 UNAVAILABLE, confía antes en el response code y en el status que en el message string. Incluso la variante Deadline expired before operation could complete sigue empezando en la rama 503, a menos que la respuesta ya sea 504 o el timeout ocurra de tu lado.
Esa regla sola evita la forma más cara de perder tiempo: arreglar la rama equivocada.