Errores de la API

En esta página, se proporciona una referencia para los códigos de error de backend que muestra la API de GenerateContent, se describe el formato de respuesta de error de gRPC y se proporcionan pasos para solucionar problemas.

Códigos de error de HTTP

En la siguiente tabla, se enumeran los códigos de error de backend comunes, las explicaciones de sus causas y las soluciones recomendadas:

Código HTTP Estado Descripción Ejemplo Solución
400 INVALID_ARGUMENT El cuerpo de la solicitud tiene un formato incorrecto. Hay un error tipográfico o falta un campo obligatorio en tu solicitud. Consulta la referencia de la API para obtener información sobre el formato de la solicitud, ejemplos y versiones compatibles. El uso de funciones de una versión de API más reciente con un extremo anterior puede causar errores.
400 FAILED_PRECONDITION El nivel gratuito de la API de Gemini no está disponible en tu país. Habilita la facturación en tu proyecto en Google AI Studio. Estás realizando una solicitud en una región en la que no se admite el nivel gratuito y no habilitaste la facturación en tu proyecto en Google AI Studio. Para usar la API de Gemini, deberás configurar un plan pagado con Google AI Studio.
403 PERMISSION_DENIED Tu clave de API no tiene los permisos necesarios. Estás usando la clave de API incorrecta; intentas usar un modelo ajustado sin pasar por la autenticación adecuada. Verifica que tu clave de API esté configurada y tenga el acceso correcto. Asegúrate de pasar por la autenticación adecuada para usar modelos ajustados.
404 NOT_FOUND No se encontró el recurso solicitado. No se encontró un archivo de imagen, audio o video al que se hace referencia en tu solicitud. Verifica si todos los parámetros de tu solicitud son válidos para tu versión de la API.
429 RESOURCE_EXHAUSTED Superaste uno de los límites de frecuencia de la API (RPM, TPM, RPD, inversión, etc.). Estás enviando demasiadas solicitudes, usando demasiados tokens o superando los límites basados en la inversión para el historial de facturación y el nivel de tu cuenta. Verifica que estés dentro de los límites de frecuencia del modelo. Espera y vuelve a intentarlo después de un breve período. Reduce la frecuencia o el tamaño de tus solicitudes. Solicita un aumento del límite de frecuencia si es necesario.
499 CANCELADO La operación se canceló (por lo general, la cancela el emisor). El cliente cerró la conexión antes de que la API pudiera terminar de responder. Verifica si tu cliente o infraestructura de red cierran la conexión de forma prematura (p.ej., debido a un tiempo de espera del cliente).
500 INTERNAL Se produjo un error inesperado en Google. El contexto de entrada es demasiado largo. Consulta la página de estado de la API de Gemini para ver si hay incidentes en curso. Reduce el contexto de entrada o cambia temporalmente a otro modelo (p.ej., de Gemini 2.5 Pro a Gemini 2.5 Flash) y comprueba si funciona. O espera un poco y vuelve a enviar la solicitud. Si el problema persiste después de volver a intentarlo, infórmalo con el botón Enviar comentarios en Google AI Studio.
503 NO DISPONIBLE Es posible que el servicio esté sobrecargado o inactivo temporalmente. El servicio se está quedando sin capacidad temporalmente. Consulta la página de estado de la API de Gemini para ver si hay incidentes en curso. Cambia temporalmente a otro modelo (p.ej., de Gemini 2.5 Pro a Gemini 2.5 Flash) y comprueba si funciona. O espera un poco y vuelve a enviar la solicitud. Si el problema persiste después de volver a intentarlo, infórmalo con el botón Enviar comentarios en Google AI Studio.
504 DEADLINE_EXCEEDED El servicio no puede terminar de procesar dentro del plazo. Tu instrucción (o contexto) es demasiado grande para procesarse a tiempo. Establece un "tiempo de espera" más largo en la solicitud del cliente para evitar este error.

Formato de respuesta de error

Cuando falla una solicitud de GenerateContent, la API establece el código de estado HTTP (como 400 Bad Request, 403 Forbidden o 429 Too Many Requests) y muestra un cuerpo de respuesta JSON que contiene detalles del estado de gRPC:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Campo Tipo Descripción
code integer El código de estado HTTP.
message string Es una descripción legible por humanos del error.
status string El código de estado de gRPC en SCREAMING_CASE.
details array Contexto de error adicional, como ErrorInfo o LocalizedMessage.

¿Qué sigue?