Resuelve los errores

La API de Gmail muestra dos niveles de información de error:

  • Códigos y mensajes de error HTTP en el encabezado
  • Un objeto JSON en el cuerpo de la respuesta con detalles adicionales que pueden ayudarte a determinar cómo controlar el error.

Las apps de Gmail deben detectar y controlar todos los errores que puedan ocurrir cuando se use la API de REST. En esta guía, se proporcionan instrucciones para resolver errores específicos de la API.

Cómo resolver un error 400: Solicitud incorrecta

Este error puede deberse a los siguientes errores en tu código:

  • No se proporcionó un campo o parámetro obligatorio.
  • El valor proporcionado o una combinación de campos proporcionados no es válido.
  • El archivo adjunto no es válido.

A continuación, se muestra una representación JSON de muestra de este error:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

Para corregir este error, revisa el campo message y ajusta el código según corresponda.

Cómo resolver un error 401: Credenciales no válidas

Un error 401 indica que el token de acceso que usas ya expiró o no es válido. Este error también puede deberse a que falta la autorización para los permisos solicitados. A continuación, se muestra la representación JSON de este error:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

Para corregir este error, actualiza el token de acceso con el token de actualización de larga duración. Si usas una biblioteca cliente, esta controla automáticamente la actualización de tokens. Si esto falla, dirige al usuario a través del flujo de OAuth, como se describe en Cómo autorizar tu app con Gmail.

Para obtener más información sobre los límites de Gmail, consulta Límites de uso.

Cómo resolver un error 403: Se superó el límite de uso

Se produce un error 403 cuando se supera un límite de uso o el usuario no tiene los privilegios correctos. Para determinar el tipo de error específico, evalúa el campo reason del JSON que se muestra. Este error ocurre en las siguientes situaciones:

  • Se superó el límite diario.
  • Se superó el límite de frecuencia de los usuarios.
  • Se superó el límite de frecuencia del proyecto.
  • Tu app no se puede usar dentro del dominio del usuario autenticado.

Para obtener más información sobre los límites de Gmail, consulta Límites de uso.

Cómo resolver un error 403: Se superó el límite diario

Un error dailyLimitExceeded indica que se alcanzó el límite de API de cortesía de tu proyecto. A continuación, se muestra la representación JSON de este error:

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

Para corregir este error:

  1. Ve a la Consola de API de Google.
  2. Elige tu proyecto.
  3. Haz clic en la pestaña Cuotas.
  4. Solicita una cuota adicional. Para obtener más información, consulta Solicita cuota adicional.

Para obtener más información sobre los límites de Gmail, consulta Límites de uso.

Cómo resolver un error 403: Se superó el límite de frecuencia del usuario

Un error userRateLimitExceeded indica que se alcanzó el límite por usuario. A continuación, se muestra la representación JSON de este error:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

Para corregir este error, intenta optimizar el código de tu aplicación para realizar menos solicitudes o volver a intentarlas. Para obtener información sobre cómo reintentar solicitudes, consulta Cómo reintentar solicitudes con errores para resolverlos.

Para obtener más información sobre los límites de Gmail, consulta Límites de uso.

Cómo resolver un error 403: Se superó el límite de frecuencia

Un error rateLimitExceeded indica que el usuario alcanzó la tasa máxima de solicitudes de la API de Gmail. Este límite varía según el tipo de solicitudes. A continuación, se muestra la representación JSON de este error:

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

Para corregir este error, vuelve a intentar con las solicitudes que fallaron.

Para obtener más información sobre los límites de Gmail, consulta Límites de uso.

Cómo resolver un error 403: La app con el ID {appId} no se puede usar en el dominio del usuario autenticado

Se produce un error domainPolicy cuando la política del dominio del usuario no permite que tu app acceda a Gmail. A continuación, se muestra la representación JSON de este error:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

Para corregir este error:

  1. Infórmale al usuario que el dominio no permite que tu app acceda a Gmail.
  2. Pídele al usuario que se comunique con el administrador del dominio para solicitar acceso a tu app.

Cómo resolver un error 429: Demasiadas solicitudes

Puede producirse un error 429 "Se realizaron demasiadas solicitudes" debido a los límites diarios por usuario (incluidos los límites de envío de correo electrónico), los límites de ancho de banda o un límite de solicitudes simultáneas por usuario. A continuación, se incluye información sobre cada límite. Sin embargo, cada límite se puede resolver reintentando las solicitudes fallidas o dividiendo el procesamiento en varias cuentas de Gmail. Los límites por usuario no se pueden aumentar por ningún motivo. Para obtener más información sobre los límites, consulta Límites de uso.

Límites de envío de correo electrónico

La API de Gmail aplica los límites estándar de envío de correo electrónico diario. Estos límites difieren para los usuarios que pagan Google Workspace y los usuarios de prueba de gmail.com. Para conocer estos límites, consulta Límites de envío de Gmail en Google Workspace.

Estos límites son por usuario y los comparten todos los clientes del usuario, ya sean clientes de API, clientes nativos o web, o MSA de SMTP. Si se superan estos límites, se muestra un error HTTP 429 Too Many Requests "Se superó el límite de frecuencia del usuario" "(envío de correo electrónico)" con tiempo para volver a intentarlo. Ten en cuenta que el exceso de los límites diarios puede generar estos tipos de errores durante varias horas antes de que se acepte la solicitud.

La canalización de envío de correo electrónico es compleja: una vez que el usuario supera su cuota, puede haber una demora de varios minutos antes de que la API comience a mostrar respuestas de error 429. Por lo tanto, no puedes suponer que una respuesta 200 significa que el correo electrónico se envió correctamente.

Límites de ancho de banda

La API tiene límites de ancho de banda de carga y descarga por usuario que son iguales a los de IMAP, pero independientes de ellos. Estos límites se comparten entre todos los clientes de la API de Gmail para un usuario determinado.

Por lo general, estos límites solo se alcanzan en situaciones excepcionales o abusivas. Si se superan estos límites, se muestra un error HTTP 429 Too Many Requests "Se superó el límite de frecuencia del usuario" con un tiempo para volver a intentarlo. Ten en cuenta que el exceso de los límites diarios puede generar estos tipos de errores durante varias horas antes de que se acepte la solicitud.

Solicitudes simultáneas

La API de Gmail aplica un límite de solicitudes simultáneas por usuario (además del límite de frecuencia por usuario). Todos los clientes de la API de Gmail que acceden a un usuario determinado comparten este límite y se garantiza que ningún cliente de la API sobrecargue el buzón de usuario de Gmail ni su servidor de backend.

Realizar muchas solicitudes en paralelo para un solo usuario o enviar lotes con una gran cantidad de solicitudes puede activar este error. Una gran cantidad de clientes de API independientes que acceden al buzón de usuario de Gmail de forma simultánea también pueden activar este error. Si se supera este límite, se muestra el error HTTP 429 Too Many Requests "Demasiadas solicitudes simultáneas para el usuario".

Cómo resolver un error 500: Error de backend

Se produce un backendError cuando surge un error inesperado mientras se procesa la solicitud.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

Para corregir este error, vuelve a intentar con las solicitudes que fallaron. A continuación, se muestra una lista de los errores 500:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Vuelve a intentar con las solicitudes fallidas para resolver los errores

Puedes reintentar periódicamente una solicitud con errores durante un período cada vez más largo para controlar los errores relacionados con los límites de frecuencia, el volumen de red o el tiempo de respuesta. Por ejemplo, puedes volver a intentar una solicitud fallida después de un segundo, luego después de dos segundos y, luego, después de cuatro segundos. Este método se denomina retirada exponencial y se usa para mejorar el uso del ancho de banda y maximizar la capacidad de procesamiento de solicitudes en entornos simultáneos.

Inicia los períodos de reintento al menos un segundo después del error.

Consulta o cambia los límites de uso y aumenta la cuota

Para consultar o cambiar los límites de uso de tu proyecto, o bien solicitar un aumento de la cuota, haz lo siguiente:

  1. Si no tienes una cuenta de facturación para tu proyecto, crea una.
  2. Visita la página de API habilitadas de la biblioteca de API en la Consola de APIs y selecciona una API de la lista.
  3. Si deseas consultar y cambiar la configuración de cuotas, selecciona la opción Cuotas. Para consultar las estadísticas de uso, selecciona la opción Uso.

Utiliza solicitudes por lotes

Se recomienda usar el procesamiento por lotes. Sin embargo, es probable que los tamaños de lotes más grandes activen el límite de frecuencia. No se recomienda enviar lotes de más de 50 solicitudes. Para obtener información sobre cómo agrupar solicitudes, consulta Solicitudes por lotes.