LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Outlook
Calendario de Google
Únase a la comunidad SlackErrores comunes de Google OAuth y la API de Gmail (y cómo solucionar cada uno)
Todo desarrollador que integre Gmail o Google Calendar con Google OAuth se encontrará con al menos uno de estos errores de Google OAuth. Esta guía consolida los 7 errores comunes de Google OAuth en un solo lugar, con la causa exacta y la solución paso a paso para cada uno. Comprender estos errores de Google OAuth le ahorrará horas de depuración.
#: Intercambio de tokens de Google OAuth
import solicita
token_respuesta = requests.post(
"https://oauth2.googleapis.com/token",
datos={
"código": código_autorización,
"id_cliente": ID_DEL_CLIENTE,
"secreto_del_cliente": CLIENT_SECRET,
"uri_de_redirección": REDIRECT_URI,
"grant_type": "código_de_autorización"
}
)Referencia rápida: todos los errores de OAuth de Google de un vistazo
Tabla resumen de todos los 7 errores de Google OAuth cubiertos en esta guía - etapa en la que ocurre, causa raíz y el enlace de solución rápida a la sección detallada a continuación. Marque esta tabla como referencia al depurar errores de Google OAuth en desarrollo o producción.
| Mensaje de error | Escenario | Causa raíz | Reparación rápida |
|---|---|---|---|
| redirect_uri_mismatch | Authorization | La URI de redirección en tu solicitud no coincide exactamente con una registrada en la Consola de Google Cloud | Arregla |
| política_de_administración_impuesta | Authorization | Un superadministrador de Workspace ha restringido las aplicaciones OAuth o los ámbitos a los que los usuarios de la organización pueden otorgar acceso | Arregla |
| acceso_denegado | Authorization | La aplicación está en modo de prueba y el usuario no es un usuario de prueba, o la aplicación solicita ámbitos restringidos sin verificación | Arregla |
| concesión_inválida | Refresco de token | El token de actualización ha expirado, ha sido revocado o se ha utilizado más de una vez (código de autenticación de uso único) | Arregla |
| Pantalla de consentimiento faltante | Consola de Google Cloud | La nueva interfaz de Google Cloud movió la pantalla de consentimiento de OAuth; también requiere el rol de Propietario/Editor en el proyecto. | Arregla |
| alcance_invalido | Authorization | Error tipográfico en la URL del ámbito o la API de Google correspondiente no está habilitada en el proyecto | Arregla |
| Google no ha verificado | Authorization | La app utiliza alcances sensibles/restringidos pero no ha completado la verificación de Google; El modo de prueba limita a 100 usuarios | Arregla |
Error 400: redirect_uri_mismatch
Este es el error más común de Google OAuth para los desarrolladores que configuran una nueva integración. Se dispara durante el paso de autorización, antes de que se emita ningún token.
El mensaje de error exacto
Error 400: redirect_uri_mismatch
La URI de redireccionamiento en la solicitud no coincidió con una URI de redireccionamiento registrada.
error=redirect_uri_mismatch
Causa
Google compara uri_redireccionamiento parámetro que pasas en tu URL de autorización con la lista de URIs de redireccionamiento autorizadas registradas en tu cliente OAuth en la Consola de Google Cloud. Incluso una diferencia de un solo carácter: una barra final, http vs https, o un puerto diferente, desencadena este error.
Arreglar (paso a paso)
https://yourapp.com/oauth/callback. El valor debe ser idéntico carácter por carácter, incluyendo el esquema, el puerto y la barra final.
uri_redireccionamiento el valor que pasas al endpoint de autorización y al endpoint de intercambio de tokens son idénticos.
redirect_uri_mismatch en localhost
Durante el desarrollo local, registra la URI exacta de localhost que utilizas, por ejemplo http://localhost:3000/callback. Google permite http:// (no solo https://) para las URI de localhost. Si cambias el puerto de desarrollo, recuerda actualizar la URI registrada.
Estos son dos campos separados y sirven para propósitos diferentes. Los orígenes de JavaScript autorizados se utilizan para flujos OAuth del lado del navegador (flujo implícito, Google Identity Services). Las URI de redireccionamiento autorizadas se utilizan para flujos de código de autorización del lado del servidor. Agregar una URI a los orígenes de JavaScript NO solucionará redirect_uri_mismatch error - debes agregarlo al campo de URIs de redirección. Un cliente OAuth de Google puede tener hasta 100 URIs de redirección registradas.
Error 400: política de administrador impuesta
Este error no es un error en tu código. Es una política organizacional impuesta por un superadministrador de Google Workspace. Un desarrollador común no puede solucionarlo solo.
El mensaje de error exacto
Error 400: admin_policy_enforced
No se puede usar la Cuenta de Google para la autorización debido a las políticas de tu organización. Ponte en contacto con tu administrador para obtener más información.
error=admin_policy_enforced
Causa
Un superadministrador de Google Workspace ha restringido qué aplicaciones de terceros o ámbitos de OAuth los usuarios de la organización pueden autorizar. Esto se configura mediante Controles de la API en la Consola de Administración de Google. Cuando una aplicación no está en la lista de aprobadas, todos los usuarios de ese Workspace recibirán este error cuando intenten autorizarla, independientemente del estado de verificación de la aplicación.
Esto es un control de cumplimiento y seguridad, no una mala configuración del lado del desarrollador. La resolución correcta es siempre del lado del administrador.
Corregir (solo del lado del administrador)
Un usuario que se encuentra política_de_administración_impuesta no pueden resolverlo por sí mismos. Necesitan ponerse en contacto con su superadministrador de Google Workspace y solicitar que la aplicación OAuth específica sea marcada como Confiable. Si el usuario es el administrador, puede seguir los pasos anteriores. Si el dominio aplica una política estricta de "Permitir aplicaciones específicas", la aplicación debe agregarse primero explícitamente a la lista de aprobadas antes de que pueda configurarse como Confiable.
Si estás creando herramientas internas y quieres evitar por completo el consentimiento OAuth por usuario, una cuenta de servicio con Delegación de Dominio Completo es la alternativa; consulta nuestra Cuenta de servicio de Gmail y guía DWD.
acceso_denegado. "Esta aplicación está bloqueada" (aplicación no verificada)
Los usuarios ven una pantalla de "Esta aplicación está bloqueada" o reciben acceso_denegado en la devolución de llamada de OAuth. Esta tiene múltiples causas raíz dependiendo de si tu aplicación todavía está en modo de prueba o apunta a ámbitos restringidos.
El mensaje de error exacto
Acceso bloqueado: [Nombre de tu aplicación] no ha completado el proceso de verificación de Google
error=access_denied
-- o --
Esta aplicación está bloqueada.
Esta aplicación intentó acceder a información sensible en tu Cuenta de Google.
Ponte en contacto con el desarrollador para obtener más información.
Causas
Mientras tu aplicación OAuth se encuentre en estado de publicación "Prueba", solo los usuarios añadidos explícitamente como usuarios de prueba pueden autorizarla. Cualquier otra persona recibirá inmediatamente un acceso denegado.
El modo de prueba está limitado a 100 usuarios de prueba únicos en cualquier momento. Una vez que se alcance el límite de 100, los nuevos usuarios no podrán autorizar la aplicación, incluso si se agregan.
Alcances como gmail.modificar o gmail.enviar son Ámbitos confidenciales. Las aplicaciones que los solicitan deben completar el proceso de verificación de aplicaciones de Google antes de que los usuarios reales puedan otorgar acceso.
Un pequeño número de alcances (por ejemplo, acceso completo a Gmail) están Restringidos y requieren una auditoría de seguridad de terceros (CASA) además de la verificación.
Arregla
invalid_grant: "vuelve a conectar tu cuenta de Gmail"
En concesión inválida de la API de Gmail el error es uno de los más confusos en producción: falla silenciosamente para un subconjunto de usuarios y requiere un nuevo flujo de OAuth para recuperarse. Comprender el ciclo de vida del token de actualización es la clave para manejarlo correctamente.
El mensaje de error exacto
{"error": "invalid_grant", "error_description": "El token ha expirado o ha sido revocado."}
-- o --
{"error": "invalid_grant", "error_description": "Solicitud incorrecta"}
Causa: el ciclo de vida del token de actualización
Solucionar: volver a autorizar con access_type=offline + prompt=consent
from google_auth_oauthlib.flow import Fluir
flujo = Flujo.desde_archivo_de_secretos_del_cliente(
'client_secrets.json',
alcances=['https://www.googleapis.com/auth/gmail.readonly'],
redirect_uri=URI_DE_REDRECCIÓN
)
# access_type=offline → obtener un token de actualización
# prompt=consent → obliga a renovar el consentimiento; siempre devuelve un nuevo token de actualización
auth_url, estado = flujo.url_de_autorización(
tipo_de_acceso='desconectado',
prompt='consentimiento'
)
# Guarda el NUEVO refresh_token de la respuesta
El token antiguo # ya no es válido: actualiza tu base de datosEvitar concesión_inválida en producción: siempre usar access_type=offline y consentimiento al iniciar el flujo OAuth, actualiza tu token de actualización almacenado cada vez que el usuario reautorice, detecta concesión_inválida errores y activar una interfaz de IU de reautorización elegante (un "vuelve a conectar tu cuenta de Gmail", mensaje), y sacar tu aplicación del modo de prueba para obtener tokens permanentes.
La pantalla de consentimiento de OAuth no aparece en la Consola de Google Cloud
Esta es la consulta de búsqueda de mayor volumen en este clúster (más de 390 búsquedas mensuales). La página de la "pantalla de consentimiento de OAuth" parece haber desaparecido de la consola de Google Cloud para muchos desarrolladores en 2024-2026 debido a un rediseño de la interfaz de usuario. No se ha eliminado, se ha movido.
Síntoma
Abres Google Cloud Console y navegas a APIs y Servicios, pero el elemento del menú "Pantalla de consentimiento de OAuth" falta o al hacer clic en él te redirige a una nueva "Descripción general de OAuth" página que muestra un panel de resumen en lugar del formulario de configuración que esperabas.
Causas
Arreglar (paso a paso)
https://console.cloud.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID. Este enlace profundo omite la página general y va directamente a la configuración de la pantalla de consentimiento. Para un recorrido completo de cada campo de configuración, selección de tipo de usuario y el límite de prueba de 100 usuarios, consulte nuestra Guía de configuración de la pantalla de consentimiento de OAuth.
Semanas de verificación.
Utilice Llave de Unipile y empezar ahora.
No pierdas clientes esperando la revisión de Google. Conecta cuentas de Gmail en 5 minutos con nuestras credenciales de desarrollador preverificadas.
alcance_invalido
Un error tipográfico en la URL del alcance o una API deshabilitada harán que Google rechace toda la solicitud de autorización antes de que ocurra cualquier interacción con el usuario.
El mensaje de error exacto
{"error": "alcance_invalido",
"error_description": "Algunos alcances solicitados fueron inválidos.
{válido=[https://mail.google.com/], inválido=[gmail.readonly]}"}
-- o en la URL de la pantalla de consentimiento --
error=invalid_scope&error_description=Some+requested+scopes+were+invalid
Causa
Dos causas fundamentales comunes: (1) el valor del ámbito es un nombre corto como gmail.lectura en lugar de la URL completa https://www.googleapis.com/auth/gmail.readonly, o (2) la API de Gmail (o cualquier otra API de Google que estés definiendo) no está habilitada en el proyecto de Google Cloud.
Ámbitos comunes de Gmail y sus URL correctas
| URL del ámbito (use la URL completa) | Lo que permite | Tipo |
|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Leer todos los mensajes y hilos | Sensible |
| https://www.googleapis.com/auth/gmail.send | Enviar correo electrónico en nombre del usuario | Sensible |
| https://www.googleapis.com/auth/gmail.modify | Leer, componer, enviar, eliminar hilos | Sensible |
| https://mail.google.com/ | Acceso completo al buzón (IMAP/SMTP) | Restringido |
| https://www.googleapis.com/auth/userinfo.email | Leer solo la dirección de correo electrónico del usuario | Básico |
Arregla
https://www.googleapis.com/auth/ o https://mail.google.com/. Nunca uses la forma corta como gmail.lectura.
"Google no ha verificado esta app" y el límite de 100 usuarios
La pantalla de advertencia "Google no ha verificado esta aplicación" aparece cuando una aplicación no verificada solicita ámbitos sensibles o restringidos. Si bien los usuarios pueden continuar haciendo clic en "Avanzado" y luego en "Ir a [nombre de la aplicación] (no seguro)", esto no es adecuado para producción, y el modo de prueba limita su aplicación a un total de 100 usuarios únicos.
Causa
Cuando tu app solicita ámbitos confidenciales (como el de gmail.lectura o gmail.enviar), Google muestra esta pantalla de advertencia a todos los usuarios hasta que complete la revisión de verificación. Para los ámbitos restringidos, también deberá aprobar una auditoría de seguridad de terceros (CASA Nivel 2).
Mientras está en estado de publicación de Pruebas, esta pantalla de advertencia también se muestra incluso para los usuarios de prueba, y el número total de usuarios de prueba permitidos está limitado a 100. Los tokens para los usuarios de prueba expiran después de 7 días.
Arregla
https://mail.google.com/adicionalmente completar una CASA Nivel 2 evaluación de seguridad por un evaluador aprobado por Google.
Estos errores desaparecen cuando el proyecto OAuth ya está certificado
La pantalla "Google no ha verificado esta aplicación", el límite de 100 usuarios y la caducidad del token de 7 días en el modo de prueba son todos síntomas de "Poseer y gestionar tu propio proyecto de Google Cloud". Un intermediario técnico independiente que actúa en nombre de cada usuario autenticado - y ya ha completado la certificación CASA Nivel 2 - elimina toda esta sobrecarga de tu lado. Tus usuarios autorizan una vez; el ciclo de vida del token, el cumplimiento del alcance y la verificación de nuevo se gestionan a nivel de plataforma.
Esto no es una solución alternativa para la revisión de seguridad de Google. Unipile ha completado de forma independiente el nivel 2 de la CASA y no está afiliado, respaldado ni patrocinado por Google.
Inicia sesión con Google OAuth ya certificadoCómo evitar toda esta clase de errores de Google OAuth
Al observar los 7 errores de Google OAuth en esta guía, surge un patrón. Todos y cada uno de ellos se originan en la misma raíz: la gestión manual de tu propio proyecto de Google Cloud y su configuración de OAuth. Estos errores de Google OAuth no son aleatorios, son consecuencias estructurales de tener un proyecto OAuth no verificado, desde desajustes en las URI de redirección y fallas en la rotación de tokens hasta el límite de 100 usuarios y el rechazo de la pantalla de consentimiento.
Hay otra manera. Usando un intermediario técnico independiente que actúa en nombre de cada usuario autenticado - que ya ha completado la revisión de verificación de Google y la certificación de seguridad CASA Nivel 2 - elimina todos estos modos de falla de su plato. La comparación a continuación muestra exactamente qué errores desaparecen y qué infraestructura Unipile maneja en su lugar. Ver Documentación de Google OAuth de Unipile para la guía de integración completa.
Todo error en esta guía: ¿quién posee la solución?
Los 7 errores de Google OAuth cubiertos anteriormente comparten una raíz común: tú eres el propietario del proyecto de Google Cloud, por lo tanto, eres el propietario de todos los modos de falla. Aquí hay una comparación lado a lado de lo que eso significa en la práctica.
La distinción clave: Unipile ya ha completado la revisión de seguridad de Google y la evaluación CASA Nivel 2 para las conexiones que gestiona en su nombre. Esto no es una solución alternativa para la revisión de seguridad de Google: Unipile ya la ha superado. Sus usuarios obtienen una pantalla de consentimiento limpia (sin advertencia de "aplicación no verificada"), su aplicación se lanza de inmediato y usted puede llevar a cabo su propia verificación de Google Cloud en paralelo sin ninguna presión de plazo de producción.
Nota de cumplimiento: Unipile es un intermediario técnico independiente, no afiliada, respaldada ni patrocinada por Google. El cliente OAuth de Google de Unipile cuenta con la certificación CASA Nivel 2, lo que permite a sus usuarios autorizar el acceso a Gmail sin una advertencia de "aplicación no verificada" para las conexiones intermediadas a través de Unipile. Esto no es una solución alternativa para la revisión de seguridad de Google: Unipile ya la ha superado para las conexiones que intermedia. en nombre de cada usuario autenticado. Los usuarios pueden revocar el acceso en cualquier momento a través de la página de permisos de su Cuenta de Google.
Preguntas frecuentes sobre errores de Google OAuth
Respuestas a las preguntas más comunes sobre errores de OAuth de Google y errores de la API de Gmail, cubriendo el ciclo de vida de los tokens, políticas de administración, URIs de redirección y configuración de la consola de Google Cloud.
política_de_administración_impuesta significa que un superadministrador de Google Workspace ha bloqueado tu aplicación o los alcances específicos de OAuth que solicita para que no sean autorizados por los usuarios de esa organización. Es una política de control de acceso organizacional, no un error en tu código. La solución requiere la intervención del superadministrador de Workspace en la Consola de Administración de Google en Seguridad > Controles de API > Administrar acceso de aplicaciones de terceros.
No. Un usuario normal no puede solucionar admin_policy_enforced. Solo una cuenta de Google Workspace superadministrador puede resolver este error marcando la aplicación como Confiable en la Consola de Administración. El usuario afectado debe ponerse en contacto con su administrador de TI o el superadministrador de Workspace y solicitar que la aplicación OAuth específica se agregue a la lista aprobada.
En redirect_uri_mismatch en localhost ocurre cuando la URI que registras en la consola de Google Cloud no coincide exactamente con la URI que utiliza tu servidor de desarrollo local. Por ejemplo, al registrar http://localhost:3000/callback pero ejecutándose en el puerto 3001, o olvidando una barra final. Google permite http:// (no solo https://) para URIs de localhost. Registra la URI exacta que usa tu servidor local, incluyendo el número de puerto correcto.
No. Los orígenes de JavaScript autorizados y las URIs de redirección autorizadas son dos campos separados. Los orígenes de JavaScript se utilizan exclusivamente para flujos OAuth del lado del navegador. Para solucionar redirect_uri_mismatch, debes añadir el URI URIs de redireccionamiento autorizados campo, no a los orígenes de JavaScript.
Un único cliente OAuth 2.0 de Google puede tener hasta 100 URIs de redireccionamiento autorizados registrado. Esto te permite registrar URIs para diferentes entornos (desarrollo local, staging, producción) y diferentes rutas de callback dentro del mismo cliente.
Si tu aplicación está en Probando el estado de publicación, los tokens de actualización de Google caducan después de 7 días independientemente del uso. Esto se debe al diseño para aplicaciones no verificadas. Pasar al estado de producción haciendo clic Publicar aplicación en la página de la pantalla de consentimiento de OAuth para obtener tokens de larga duración. En Producción, los tokens de actualización permanecen válidos siempre que el usuario use tu aplicación al menos una vez cada 6 meses. Para una alternativa administrada, visita nuestro Solución de API de Gmail gestionada.
Google revoca los tokens de actualización que no se han utilizado durante 6 meses (aproximadamente 180 días). Los tokens también se revocan cuando: el usuario cambia su contraseña de la cuenta de Google, el usuario revoca el acceso a la aplicación en la configuración de seguridad de su Cuenta de Google, se reautoriza con ámbitos diferentes o el número total de tokens de actualización para un par usuario-aplicación único supera los 50 (los más antiguos se revocan primero). Para obtener una imagen completa sobre cómo crear integraciones de correo electrónico robustas, consulte nuestras Guía completa de la API de correo electrónico.
Google rediseñó la Cloud Console en 2024. La configuración de la pantalla de consentimiento de OAuth ahora se encuentra dentro de APIs y Servicios > Descripción general de OAuth. Hacer clic Editar aplicación o usa las pestañas Marca, Audiencia y Alcances. Consulta también: necesitas Rol de editor o propietario en el proyecto (el espectador no puede acceder al formulario) y asegúrate de estar en el proyecto correcto usando el selector de proyectos en la parte superior de la consola.
¿Sigues encontrando un error de Google OAuth que no aparece aquí? Omite la depuración y deja que Unipile se encargue del OAuth de Gmail por ti.
Construir
ES 
EN 
FR 
DE 
IT 
BR 
NL 
PL 
TR