«The model is overloaded» es el único error de Gemini que no tiene que ver contigo: el grupo de servidores de ese modelo no tiene capacidad en este momento. Ninguna configuración de tu proyecto puede evitarlo; lo que controlas es cómo superarlo y a qué alternativa recurrir si no desaparece.
El error
{
"error": {
"code": 503,
"message": "The model is overloaded. Please try again later.",
"status": "UNAVAILABLE"
}
}Causas y soluciones de un vistazo
| Causa | Solución |
|---|---|
| Pico de demanda en el grupo de servidores de ese modelo | Retroceso exponencial con jitter; el pico suele pasar en segundos o unos minutos. |
| Variantes de modelos preliminares / experimentales | Las compilaciones -exp y preview funcionan en grupos pequeños y se sobrecargan primero. Fija el alias estable para producción. |
| Solicitudes pesadas durante las horas punta | Los contextos enormes y los límites máximos de salida tienen más probabilidades de ser descartados bajo carga; reduce lo que no necesites y transmite la respuesta. |
Confirma que sea 503 UNAVAILABLE, no 429
429 RESOURCE_EXHAUSTED es tu cuota; 503 UNAVAILABLE es la capacidad de Google. La distinción determina todo lo demás: los errores de cuota requieren cambios de facturación o de límites, mientras que los errores de capacidad requieren reintentos y alternativas. No depures la configuración de tu proyecto por un 503: no encontrarás nada allí.
Reintentar con retroceso, pero con un presupuesto
503 es reintentable por definición. Usa el mismo retroceso exponencial con jitter que para cualquier 429 (el fragmento de nuestra guía de Claude 429 funciona sin cambios: ya reintenta los estados de la clase 500), pero limita la espera total a lo que tu cliente pueda tolerar; si la sobrecarga supera unos 5 intentos durante un minuto, no desaparecerá rápidamente.
Cuando se agotan los reintentos: cambia el modelo, no el bucle
Prepara una cadena de alternativas antes de necesitarla: el alias estable si utilizabas una versión preliminar, gemini-2-5-flash si 2.5 Pro tiene problemas (o viceversa), o incluso otro proveedor para la solicitud que no puede fallar. Las alternativas convierten una interrupción en una degradación de calidad.
Si llamas a través de Kunavo
Este modo de fallo explica por qué Kunavo reintenta dentro de la solicitud: cuando hay configurado más de un canal ascendente para un modelo, un intento fallido pasa al otro canal antes de que veas el error; un fallo ascendente transitorio se convierte en un éxito más lento en lugar de un 503. Las solicitudes fallidas nunca se facturan y, como una sola clave cubre Gemini, Claude y GPT, la alternativa entre proveedores del paso 3 consiste en cambiar la cadena del modelo, no en realizar una segunda integración. ¿Estás evaluando un modelo alternativo? Las tarifas por token de toda la familia Gemini, junto con los precios de lista de Google, están en la lista de precios de la API de Gemini.
Preguntas frecuentes
¿Se me cobran las solicitudes que devuelven 503?
No: la solicitud se rechaza antes de la inferencia, por lo que Google no la factura, y en Kunavo las solicitudes fallidas tampoco se facturan. El coste de un 503 es latencia y reintentos, no tokens.
¿Cuánto duran las sobrecargas de Gemini?
Normalmente, de unos segundos a unos minutos; los picos del día de lanzamiento de un modelo nuevo pueden durar más. Por eso, la política sensata es realizar varios reintentos con retroceso y después usar un modelo alternativo, no un bucle de reintentos ilimitado.
¿Pasar a un nivel de pago evita los 503?
No. Los niveles de pago aumentan tus cuotas (la familia 429), pero 503 UNAVAILABLE corresponde a la capacidad de servicio compartida: el tráfico gratuito y el de pago lo experimentan cuando un grupo está saturado. La mitigación son las alternativas, no la facturación.
Guías relacionadas
- Precios de la API de Google Gemini septiembre de 2026 — tarifa oficial y precios por token 2026
- API de Gemini 3: precios, disponibilidad y cómo llamar a Gemini hoy
Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.