La API de Gmail devuelve dos niveles de información de error:
- Códigos y mensajes de error HTTP en el encabezado
- 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 surgir cuando se usa 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 la combinación de campos proporcionados no son válidos.
- El archivo adjunto no es válido.
A continuación, se muestra un ejemplo de la representación JSON 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.
Cómo resolver un error 401: Credenciales no válidas
Un error 401 indica que el token de acceso que estás usando expiró o no es válido. Este error también puede deberse a la falta de autorización para los alcances 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 del token. Si 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 específico de error, evalúa el campo reason del JSON que se devuelve. Este error ocurre en las siguientes situaciones:
- Se superó el límite diario.
- Se superó el límite de frecuencia del usuario.
- Se superó el límite de frecuencia del proyecto.
- No se puede usar tu app en el 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 la API de cortesía para 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:
- Visita la Consola de APIs de Google.
- Elige tu proyecto.
- Haz clic en la pestaña Cuotas.
- Solicita 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 Reintenta solicitudes con errores para resolver errores.
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 las solicitudes fallidas.
Para obtener más información sobre los límites de Gmail, consulta Límites de uso.
Cómo resolver un error 403: No se puede usar la app con el ID {appId} 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:
- Informa al usuario que el dominio no permite que tu app acceda a Gmail.
- Indícale al usuario que se comunique con el administrador del dominio para solicitar acceso a tu app.
Cómo resolver el error 429: Demasiadas solicitudes
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. 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 correos electrónicos
La API de Gmail aplica los límites estándar de envío de correo diarios. Estos límites son diferentes para los usuarios de que pagan y los usuarios de prueba de gmail.com. Para conocer estos límites, consulta Límites de envío de Gmail en .
Estos límites son por usuario y se comparten entre 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 el tiempo para volver a intentarlo.
Ten en cuenta que, si se superan los límites diarios, es posible que se produzcan este tipo de errores durante varias horas antes de que se 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. 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 este. 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 de reintento.
Ten en cuenta que, si se superan los límites diarios, es posible que se produzcan 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, lo que garantiza que ningún cliente de la 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 correo del 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 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 las solicitudes fallidas. A continuación, se incluye una lista de 500 errores:
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Vuelve a intentar las solicitudes que fallaron 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 solicitudes en entornos simultáneos.
Comienza los períodos de reintento al menos un segundo después del error.
Ver o cambiar los límites de uso y aumentar 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:
- 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.
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 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.