Los errores de la API de Gemini parecen muy variados, pero en la práctica casi todos caen en cuatro categorías: identidad incorrecta, dirección incorrecta, cuota insuficiente y red inaccesible. Los problemas causados por el propio modelo son minoritarios.

Este artículo desglosa cada tipo de error y propone un orden de diagnóstico que empieza por la petición mínima. Cuando surja un problema, guarda primero el JSON completo del error y comprueba los puntos en orden; no cambies a la vez la clave, la dirección y el modelo.

Nota: Google y Gemini son marcas de sus respectivos titulares. Este artículo toma como ejemplo las formas de interfaz habituales a octubre de 2026; la versión de la interfaz, las cuotas y las políticas regionales se rigen por la documentación oficial y por la página de precios de modelos.

1. Aprende a leer el cuerpo del error

Los errores de las API de Google suelen devolver JSON con tres campos clave:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code es el código de estado HTTP, status es el tipo de error legible por máquina y message suele contener la causa concreta; en details puede aparecer el ID de cuota y la hora de reintento recomendada. Al diagnosticar hay que mirar los tres campos: quedarse solo con «429» oculta si es un límite por minuto o una cuota diaria agotada.

Código Status habitual Dirección general
401 UNAUTHENTICATED Clave ausente, inválida o colocada en el lugar equivocado
403 PERMISSION_DENIED Proyecto no habilitado, permisos o región restringida
404 NOT_FOUND Nombre de modelo, ruta de interfaz o versión incorrectos
429 RESOURCE_EXHAUSTED Límite de velocidad, concurrencia o cuota superados
400 INVALID_ARGUMENT / FAILED_PRECONDITION Parámetros incorrectos, región no compatible o condiciones previas no cumplidas
500/503 INTERNAL / UNAVAILABLE Fallo temporal del upstream; normalmente se puede reintentar con retroceso

2. 401: clave inválida o método de autenticación incorrecto

El núcleo de un 401 es que «el servidor no reconoce tu identidad». Causas habituales:

  • La petición no incluye la clave o la variable de entorno está vacía.
  • La interfaz nativa usa Authorization en lugar de x-goog-api-key.
  • La interfaz compatible con OpenAI usa x-goog-api-key en lugar de Authorization: Bearer.
  • Hay espacios o saltos de línea alrededor de la clave, o se copiaron comillas de más.
  • La clave fue eliminada o rotada, o el proyecto al que pertenece está desactivado.
  • Se envió una clave de pasarela a la dirección oficial de Google, o al revés.
  • La clave tiene restricciones de API que no permiten llamar a Gemini API.

Confirma primero con una petición mínima:

export GEMINI_API_KEY="tu-clave"

# Interfaz nativa de Gemini
curl "https://generativelanguage.googleapis.com/v1beta/models/<ID-del-modelo>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Responde solo OK"}]}]}'

# Interfaz compatible con OpenAI
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<ID-del-modelo>","messages":[{"role":"user","content":"Responde solo OK"}]}'

Los dos comandos corresponden a dos sistemas de autenticación. El que funcione indica a qué sistema pertenecen tu clave y tu dirección; si al mezclarlos aparece un 401, no significa que la clave esté rota, sino que la combinación es incorrecta.

3. 404: nombre de modelo, ruta o versión incorrectos

Un 404 no siempre significa «el modelo no existe». Situaciones habituales:

  1. El ID del modelo está mal escrito o se usó el nombre visible de la consola en lugar del identificador de la API.
  2. El modelo no pertenece a la versión actual de la API; por ejemplo, se envía a una ruta antigua un modelo que solo está disponible en la nueva.
  3. La Base URL tiene /v1 o /v1beta de más o de menos, y al concatenar la ruta se genera una dirección inexistente.
  4. La dirección termina con una barra y el cliente añade la ruta otra vez.
  5. Al llamar a través de una pasarela, el modelo no está habilitado en el grupo o plan actual.
  6. Se usa una interfaz de chat para llamar a generación de imágenes u otra interfaz específica.

Para diagnosticar, lista primero los modelos disponibles con la clave actual:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Si el modelo objetivo aparece en la lista, revisa la ruta de la petición; si no aparece, resuelve primero la habilitación del modelo o los permisos. Cuando llames a través de una pasarela, usa el ID de modelo y la Base URL que indique su documentación; no apliques directamente los nombres oficiales.

4. 429: distingue primero el límite de tasa de la cuota agotada

El 429 es el error que más se malinterpreta. Incluye al menos tres situaciones:

Tipo Rasgo típico Dirección de la solución
Límite por minuto Concurrencia alta en poco tiempo; errores concentrados en segundos Reducir la concurrencia y reintentar con retroceso
Cuota diaria agotada Se alcanza el máximo del día y los fallos persisten Esperar el reinicio, ampliar la cuota o cambiar de plan
Cuota por proyecto Varios servicios comparten proyecto y compiten entre sí Separar proyectos y claves, asignar cuotas individuales

El campo details del cuerpo del error suele indicar el ID de cuota y la hora de reintento recomendada. No reenvíes en cuanto veas un 429: una tormenta de reintentos empeora la situación. Instala primero la dependencia pip install requests. Una lógica de retroceso válida:

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<ID-del-modelo>:generateContent"
    headers = {
        "x-goog-api-key": "tu-clave",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("Se agotaron los reintentos")

Los reintentos solo resuelven la congestión temporal, no la cuota agotada. En producción también hay que añadir tiempos de espera, mecanismos de corte (circuit breakers) y un modelo de respaldo; de lo contrario, un solo 429 puede tumbar toda la cadena.

5. Restricciones por región: por qué falla la conexión directa desde China

La API de Gemini solo presta servicio en algunos países y regiones. Cuando la salida de la petición cae en una región no compatible, hay tres manifestaciones habituales:

  • Tiempo de espera de conexión o fallo del handshake TLS, normalmente por una ruta de red inaccesible.
  • 400 FAILED_PRECONDITION, con mensajes del tipo location is not supported.
  • 403 PERMISSION_DENIED, que puede estar relacionado con permisos de proyecto, facturación o región.

Hay dos conceptos que se confunden con facilidad: la región de registro de la cuenta y la región de salida de la petición. Aunque la cuenta sea válida, si el servidor está desplegado en una región no compatible la petición puede rechazarse; a la inversa, que un proxy local abra la página web no significa que las peticiones a la API salgan por la misma ruta.

Se recomienda este orden de actuación:

  1. Confirma si la petición sale del equipo local, de un contenedor o de un servidor, y localiza la IP de salida real.
  2. Comprueba si la región de salida está en la lista oficial de regiones compatibles.
  3. Revisa la región seleccionada en el servidor en la nube y cámbiala a una compatible si es necesario.
  4. Si el negocio está principalmente en China, evalúa el acceso a través de una pasarela conforme que unifique red y facturación.
  5. No conviertas «cambiar de IP» en la única solución; confirma antes las condiciones del servicio y la normativa local.

6. Otros errores frecuentes

Síntoma Causa habitual Solución
400 INVALID_ARGUMENT Estructura JSON incorrecta, orden de roles erróneo o formato de imagen no compatible Usar una petición mínima y añadir campos poco a poco
400 FAILED_PRECONDITION Región no compatible, facturación no habilitada o condiciones previas ausentes Revisar región, facturación y estado del proyecto
403 PERMISSION_DENIED API no habilitada, restricción de clave o permisos de proyecto insuficientes Habilitar en la consola y verificar permisos
500 INTERNAL Error interno del upstream Reintentar con retroceso y registrar el ID de petición
503 UNAVAILABLE Sobrecarga o mantenimiento del upstream Reintentar con retroceso y cambiar al modelo de respaldo
Hay respuesta pero sin contenido Bloqueo por política de seguridad o salida truncada Revisar blockReason y finishReason
La salida se detiene a mitad Se alcanzó el máximo de tokens de salida Aumentar el límite o acortar la entrada

«Hay respuesta pero no contenido» se interpreta a menudo como un fallo, cuando en realidad suele ser un filtro de seguridad o un límite de longitud. Revisa primero promptFeedback.blockReason, finishReason y usageMetadata en la respuesta, y decide después si cambiar el prompt o ajustar parámetros.

7. Orden de diagnóstico recomendado

  1. Guarda el JSON completo del error, la hora de la petición, el ID del modelo y el ID de petición.
  2. Envía una petición mínima con curl para descartar interferencias del cliente y del SDK.
  3. Verifica tres cosas: Base URL, cabecera de autenticación e ID del modelo.
  4. Cambia a un modelo que sepas que funciona para determinar si el problema es del modelo o de la cadena.
  5. Revisa la cuota, la facturación y el estado del proyecto, y distingue entre 429 y 403.
  6. Confirma la región de salida y la ruta de red.
  7. Por último, revisa la configuración del cliente, el proxy y la lógica de reintentos del código.

Cambia una sola variable cada vez. De lo contrario, aunque el servicio se recupere, no sabrás qué paso lo arregló y volverás a caer en el mismo problema.

8. Preguntas frecuentes

¿Cuál es la diferencia entre 401 y 403?

Un 401 significa «la identidad no se verificó»: revisa primero la clave, la cabecera de autenticación y la correspondencia con la dirección. Un 403 significa «la identidad se verificó, pero no hay permiso»: revisa si la API está habilitada, los permisos del proyecto, las restricciones de la clave y la política regional.

¿Basta con esperar unos minutos después de un 429?

Depende del tipo de cuota. El límite por minuto suele recuperarse tras el retroceso; la cuota diaria agotada requiere esperar el reinicio o ampliar la cuota. Lee primero el ID de cuota y la recomendación de reintento del cuerpo del error, y no reenvíes a ciegas.

¿Cambiar de IP resuelve la restricción por región?

No necesariamente. Hay que comprobar la región de salida real, el estado de la cuenta y las condiciones del servicio. En entornos empresariales es más seguro desplegar en una región compatible o acceder mediante una pasarela conforme.

La dirección oficial funciona, pero la pasarela devuelve 404: ¿de quién es el problema?

Revisa primero la Base URL y el ID del modelo de la pasarela. Los nombres de modelo, las rutas y el alcance disponible pueden diferir de los oficiales, así que no apliques directamente la petición oficial. Sustituye cada elemento siguiendo el ejemplo mínimo de la documentación de la pasarela.

¿Cómo evitar que los reintentos multipliquen el coste?

Fija un número máximo de reintentos, retroceso exponencial y tiempos de espera; trata los 429 por separado; añade deduplicación a las peticiones no idempotentes; y configura límites de presupuesto y alertas en la pasarela.

Siguiente paso

La clave del diagnóstico de errores de Gemini es separar primero las cuatro categorías —autenticación, ruta, cuota y red— y validar cada una con una petición mínima. Si necesitas un punto de entrada unificado y quieres reducir la incertidumbre de la conexión directa desde China, puedes registrarte en la pasarela de IA de ZSQH; los modelos, las cuotas y los precios figuran en precios de modelos.

Lecturas relacionadas: