Resuelve los errores

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

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

Tu app de Gmail debe detectar y controlar todos los errores que encuentres cuando uses la API de REST. En esta guía, se proporcionan instrucciones para resolver errores específicos de la API de Gmail.

Resumen del código de estado HTTP

Código de error Descripción
200 - OK La solicitud se procesó correctamente (esta es la respuesta estándar para las solicitudes HTTP exitosas).
400 - Bad Request El servidor no pudo completar la solicitud debido a un error del cliente.
401 - Unauthorized La solicitud contiene credenciales no válidas.
403 - Forbidden El servidor recibió y comprendió la solicitud, pero el usuario no tiene permiso para realizarla.
404 - Not Found No se pudo encontrar el recurso solicitado.
429 - Too Many Requests Se realizaron demasiadas solicitudes a la API.
500, 502, 503, 504 - Server Errors Se produjo un error inesperado mientras se procesaba la solicitud.

Errores 400

Estos errores significan que la solicitud tiene un error, a menudo debido a la falta de un parámetro obligatorio.

badRequest

Este error puede deberse a cualquiera de los siguientes problemas en tu código:

  • Falta un campo o parámetro obligatorio.
  • Un valor proporcionado o una combinación de campos no son válidos.
  • El archivo adjunto no es válido.

La siguiente muestra de JSON es una representación 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, verifica el campo message y ajusta tu código según corresponda.

Errores 401

Estos errores significan que la solicitud no contiene un token de acceso válido.

authError

Este error se produce cuando el token de acceso que usas expiró o no es válido. La falta de autorización para los permisos solicitados también puede causar este error. La siguiente muestra de JSON es una representación 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 del token. Si falla, dirige al usuario a través del flujo de OAuth, como se describe en Obtén información sobre la autenticación y la autorización.

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

Errores 403

Estos errores se producen cuando superas un límite de uso o el usuario no tiene los privilegios correctos. Para determinar la causa, evalúa el campo reason del JSON devuelto. Este error ocurre en las siguientes situaciones:

  • Tu app no se puede usar en el dominio del usuario autenticado.
  • El proyecto excedió el límite diario.
  • El usuario superó el límite de frecuencia.
  • El proyecto excedió el límite de frecuencia.

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

dailyLimitExceeded

Este error se produce cuando tu proyecto alcanza su límite de API. El siguiente ejemplo de JSON es una representación de este error:

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

Este error se produce cuando el propietario de la aplicación establece un límite de cuota para restringir el uso de un recurso en particular. Para corregir este error, aumenta la cuota en el proyecto de Google Cloud. Para obtener más información, consulta Administra los límites de cuota.

domainPolicy

Este error se produce cuando la política del dominio del usuario no permite que tu app acceda a Gmail. El siguiente JSON es la representación 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, prueba lo siguiente:

  1. Informa al usuario que el dominio no permite que tu app acceda a Gmail.
  2. Indícale al usuario que se comunique con el administrador de su dominio para solicitar acceso a tu app.

rateLimitExceeded

Este error indica que el usuario alcanzó la frecuencia máxima de solicitudes para la API de Gmail. Este límite varía según el tipo de solicitud. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, prueba lo siguiente:

userRateLimitExceeded

Este error ocurre cuando una solicitud alcanza el límite por usuario. El siguiente ejemplo de JSON es una representación 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 que realice menos solicitudes o usa la retirada exponencial para reintentar la solicitud.

Errores 429

El error 429 "Demasiadas solicitudes" puede ocurrir debido a límites diarios por usuario (incluidos los límites de envío de correo electrónico), 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 volviendo a intentar las solicitudes fallidas o dividiendo el procesamiento en varias cuentas de Gmail.

No puedes aumentar los límites por usuario. Para obtener más información sobre los límites, consulta Límites de uso.

Límites de envío de correos electrónicos

La API de Gmail aplica los límites estándar de envío de correo electrónico diarios. Estos límites son diferentes para los usuarios de Google Workspace que pagan 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 integrados o web, o MSA de SMTP. Si superas estos límites, la API devolverá un error HTTP 429 "Demasiadas solicitudes: Se superó el límite de frecuencia del usuario (envío de correo electrónico)" con un tiempo de reintento. Si se superan los límites diarios, es posible que se produzcan estos errores durante varias horas antes de que el servidor acepte la solicitud.

La canalización de envío de correos electrónicos es compleja: una vez que el usuario supera su cuota, puede haber una demora de varios minutos antes de que la API comience a devolver respuestas de error 429. 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 este. Estos límites se comparten entre todos los clientes de la API de Gmail de un usuario.

Por lo general, los usuarios solo encuentran estos límites en situaciones excepcionales o abusivas. Si superas estos límites, la API devolverá un error HTTP 429 "Demasiadas solicitudes: Se superó el límite de frecuencia del usuario" con un tiempo de reintento. Si se superan los límites diarios, es posible que se produzcan estos errores durante varias horas antes de que el servidor 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 comparten este límite, lo que garantiza que ningún cliente de la API sobrecargue el buzón de correo de un usuario de Gmail o su servidor de backend.

Realizar muchas solicitudes paralelas 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 correo del usuario de Gmail de forma simultánea también puede activar este error. Si superas este límite, la API devolverá un error HTTP 429 "Demasiadas solicitudes: Demasiadas solicitudes simultáneas para el usuario".

Errores 500, 502, 503 y 504

Estos errores se producen cuando surge un error inesperado del servidor mientras se procesa la solicitud. Varios problemas pueden causar estos errores, como la superposición del tiempo de una solicitud con otra o una solicitud para una acción no admitida, como intentar actualizar los permisos de una sola página en Google Sites en lugar de todo el sitio.

A continuación, se incluye una lista de errores 5xx:

  • 500, error de backend
  • 502 Puerta de enlace incorrecta
  • 503 Servicio no disponible
  • 504 Tiempo de espera de la puerta de enlace agotado

backendError

Este error se produce cuando surge un error inesperado durante el procesamiento de la solicitud. La siguiente muestra de JSON es una representación de este error:

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

Para corregir este error, usa la retirada exponencial para reintentar la solicitud.

Vuelve a intentar las solicitudes fallidas para resolver errores

Puedes reintentar periódicamente una solicitud con errores durante un período cada vez mayor para controlar los errores relacionados con los límites de frecuencia, el volumen de la 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 las solicitudes en entornos simultáneos.

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

Administrar límites de 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.

Para obtener más información, consulta Visualiza y administra las cuotas.

Utiliza solicitudes por lotes

Las solicitudes por lotes pueden mejorar el rendimiento, pero los tamaños de lotes más grandes pueden activar la limitación de frecuencia. No envíes lotes de más de 50 solicitudes. Para obtener información sobre cómo agrupar solicitudes en lotes, consulta Solicitudes por lotes.