La API de Gmail devuelve dos niveles de información de error:
- Códigos de error de HTTP y mensajes 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
Las apps de Gmail deben detectar y manejar todos los errores que pueden 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 el 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 un ejemplo de 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, revisa 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 está vencido o no es válido. Este error también puede deberse a la falta de 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 Autoriza tu app con Gmail.
Para obtener información adicional sobre los límites de Gmail, consulta Límites de uso.
Cómo resolver un error 403: Se excedió el límite de uso
El error 403 ocurre 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 muestra. 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 dentro del dominio del usuario autenticado.
Para obtener información adicional 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 API de Google.
- Selecciona tu proyecto.
- Haz clic en la pestaña Cuotas.
- Solicitar cuota adicional Para obtener más información, consulta Cómo solicitar una cuota adicional.
Para obtener información adicional sobre los límites de Gmail, consulta Límites de uso.
Cómo resolver un error 403: Se superó el límite de frecuencia de usuarios
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 la aplicación para realizar menos solicitudes o reintentar las solicitudes. Para obtener información sobre cómo reintentar solicitudes, consulta Reintenta las solicitudes fallidas para resolver errores.
Para obtener información adicional 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ó el porcentaje máximo 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 solucionar este error, reintenta las solicitudes erróneas.
Para obtener información adicional sobre los límites de Gmail, consulta Límites de uso.
Resuelve un error 403: No se puede usar la app con el ID {appId} dentro del dominio del usuario autenticado
Se produce un error domainPolicy cuando la política para el 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 la app acceda a Gmail.
- 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
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. Incluye información sobre cada límite. Sin embargo, cada límite se puede resolver si intentas reintentar las solicitudes con errores o si divides 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ándares de envío de correo electrónico diario. Estos límites son diferentes para los usuarios 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 los clientes de la API, los clientes nativos o web, o el MSA de SMTP. Si se superan estos límites, se muestra el error HTTP 429 Too Many Requests “Se superó el límite de tasa de usuarios” “(envío de correo electrónico)” con tiempo para volver a intentarlo.
Ten en cuenta que exceder 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 un retraso 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 al IMAP, pero son independientes. 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 de abuso.
Si se superan estos límites, se muestra el error HTTP 429 Too Many Requests
“Se superó el límite de tasa de usuarios” con un tiempo para volver a intentarlo.
Ten en cuenta que exceder 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 garantiza que ningún cliente de la API sobrecargue un buzón de correo de usuario de Gmail ni 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 simultáneamente al buzón del usuario de Gmail también puede activar este error. Si se supera este límite, se muestra el error Too Many Requests“Demasiadas solicitudes simultáneas para el usuario” de HTTP 429.
Resuelve un error 500: Error de backend
Una backendError se produce 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 solucionar este error, reintenta las solicitudes erróneas. A continuación, se muestra una lista de errores 500:
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
Reintenta las solicitudes erróneas para resolver los errores
Periódicamente, puedes reintentar una solicitud con errores durante un período creciente para manejar errores relacionados con los límites de frecuencia, el volumen de red o el tiempo de respuesta. Por ejemplo, puedes reintentar una solicitud con errores después de un segundo, luego 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
Si deseas ver o cambiar los límites de uso de tu proyecto, o 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, pero 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 Cómo agrupar solicitudes.