Resuelve los errores

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

Mensajes y códigos 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 manejar el error

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

Resumen de códigos de estado HTTP

Código de error	Descripción
`200 - OK`	La solicitud se realizó correctamente (esta es la respuesta estándar para las solicitudes HTTP correctas).
`400 - Bad Request`	No se puede completar la solicitud debido a un error del cliente en la solicitud.
`401 - Unauthorized`	La solicitud contiene credenciales no válidas.
`403 - Forbidden`	Se recibió y comprendió la solicitud, pero el usuario no tiene permiso para realizarla.
`404 - Not Found`	No se pudo encontrar la página solicitada.
`429 - Too Many Requests`	Hay demasiadas solicitudes a la API.
`500, 502, 503, 504 - Server Errors`	Se produce un error inesperado mientras se procesa la solicitud.

Errores 400

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

`badRequest`

Este error puede ocurrir por cualquiera de los siguientes problemas 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.

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 venció o no es válido. Este error también puede deberse a la falta de autorización para los alcances solicitados. 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 información adicional 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 que se muestra. Este error se produce en las siguientes situaciones:

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

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

`dailyLimitExceeded`

Este error se produce cuando se alcanza el límite de la API para tu proyecto. La siguiente muestra 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 aparece cuando el propietario de la aplicación estableció un límite de cuota para limitar 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:

Informa al usuario que el dominio no permite que tu app acceda a Gmail.
Indica 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 de 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:

Solicitar un aumento de la cuota.
Usa la retirada exponencial para reintentar la solicitud.

`userRateLimitExceeded`

Este error se produce cuando se alcanza el límite por usuario. La siguiente muestra 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 realizar menos solicitudes o usa la retirada exponencial para reintentar la solicitud.

Errores 429

Un 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 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 de envío de correo electrónico diarios estándar. Estos límites difieren 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 se comparten entre todos los clientes del usuario, ya sean clientes de API, clientes integrados o web, o MSA de SMTP. Si se superan estos límites, se muestra un error HTTP 429 "Demasiadas solicitudes: se superó el límite de frecuencia del usuario (envío de correo electrónico)" con un tiempo para reintentar. Si se superan los límites diarios, es posible que se produzcan estos 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. 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 IMAP, pero independientes de este. Estos límites se comparten entre todos los clientes de la API de Gmail para un usuario.

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 "Demasiadas solicitudes: se superó el límite de frecuencia del usuario" con un tiempo para reintentar. Si se superan los límites diarios, es posible que se produzcan estos 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). Este límite se comparte entre todos los clientes de la API de Gmail que acceden a un usuario y garantiza que ningún cliente de API sobrecargue el buzón 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 usuario de Gmail de forma simultánea también pueden activar este error. Si se supera este límite, se muestra 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, incluido el tiempo de una solicitud que se superpone con otra solicitud o una solicitud de una acción no admitida, como intentar actualizar los permisos de una sola página en Google Sites en lugar de todo el sitio.

La siguiente es una lista de errores 5xx:

Error de backend 500
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

backendError

Este error se produce cuando surge un error inesperado mientras se procesa 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 fallida durante un período cada vez más largo para controlar los errores relacionados con los límites de frecuencia, el volumen de la red o el tiempo de respuesta. Por ejemplo, puedes reintentar 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.

Inicia 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:

Si no tienes una cuenta de facturación para tu proyecto, crea una.
Visita la página de API habilitadas de la biblioteca de API en la Consola de APIs y selecciona una API de la lista.
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

Se recomienda usar solicitudes por lotes; sin embargo, es probable que los tamaños de lotes más grandes activen la limitación de frecuencia. No se recomienda enviar lotes de más de 50 solicitudes. Para obtener información sobre cómo agrupar solicitudes por lotes, consulta Solicitudes por lotes.