LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Outlook
Google Agenda
Rejoindre la communauté SlackErreurs courantes de l'API Google OAuth et Gmail (et comment résoudre chacune d'elles)
Chaque développeur qui intègre Gmail ou Google Agenda avec Google OAuth rencontrera au moins une de ces erreurs Google OAuth. Ce guide regroupe les 7 erreurs Google OAuth courantes en un seul endroit, avec la cause exacte et la solution étape par étape pour chacune d'elles. Comprendre ces erreurs Google OAuth vous fera gagner des heures de débogage.
Échange de jetons OAuth Google #
import demandes
jeton_réponse = requests.post(
"https://oauth2.googleapis.com/token",
données={
"code": code_autorisation,
"identifiant_client": ID_CLIENT,
"client_secret": SECRET_CLIENT,
"uri_redirection": URI_REDIRECTION,
"grant_type": "code_autorisation"
}
)Référence rapide : toutes les erreurs Google OAuth en un coup d'œil
Un résumé en une seule table de toutes les 7 erreurs Google OAuth abordées dans ce guide - étape où elle se produit, cause racine et lien de correction rapide vers la section détaillée ci-dessous. Marquez cette table comme référence pour le débogage des erreurs Google OAuth en développement ou en production.
| Message d'erreur | Stage | Cause profonde | Solution rapide |
|---|---|---|---|
| uri_de_redirection_introuvable | Authorization | L'URI de redirection dans votre requête ne correspond pas exactement à celui enregistré dans Google Cloud Console | Réparez-le |
| politique_admin_appliquée | Authorization | Un super administrateur Workspace a restreint les applications ou les étendues OAuth auxquelles les utilisateurs de l'organisation peuvent accorder l'accès | Réparez-le |
| accès_refusé | Authorization | L'application est en mode de test et l'utilisateur n'est pas un utilisateur de test, ou l'application demande des scopes restreints sans vérification | Réparez-le |
| grant_invalide | Rafraîchissement des jetons | Le jeton de renouvellement a expiré, a été révoqué ou utilisé plus d'une fois (code d'authentification à usage unique) | Réparez-le |
| Écran de consentement manquant | Console Google Cloud | La nouvelle interface utilisateur de Google Cloud a déplacé l'écran de consentement OAuth ; elle nécessite également le rôle Propriétaire/Éditeur sur le projet | Réparez-le |
| portée_invalide | Authorization | URL du champ d'application incorrect ou l'API Google correspondante n'est pas activée dans le projet | Réparez-le |
| Google n'a pas vérifié | Authorization | L'application utilise des scopes sensibles/restreints mais n'a pas terminé la vérification Google ; le mode test est limité à 100 utilisateurs | Réparez-le |
Erreur 400 : redirect_uri_mismatch
C'est l'erreur OAuth Google la plus courante pour les développeurs lors de la mise en place d'une nouvelle intégration. Elle se déclenche pendant l'étape d'autorisation, avant même la délivrance d'un jeton.
Le message d'erreur exact
Erreur 400 : redirect_uri_mismatch
L'URI de redirection dans la requête ne correspondait pas à un URI de redirection enregistré.
error=redirect_uri_mismatch
Cause
Google compare le uri_de_redirection paramètre que vous passez dans votre URL d'autorisation avec la liste des URI de redirection autorisées enregistrées dans votre client OAuth dans la console Google Cloud. Même une différence d'un seul caractère - une barre oblique finale, http vs https, ou un port différent - déclenche cette erreur.
Réparez (étape par étape)
https://yourapp.com/oauth/callback. La valeur doit être identique caractère pour caractère, y compris le schéma, le port et la barre oblique finale.
uri_de_redirection la valeur que vous transmettez au point d'accès d'autorisation et au point d'accès d'échange de jetons sont identiques.
redirection_uri_mismatch sur localhost
Lors du développement local, enregistrez l'URI localhost exacte que vous utilisez - par exemple http://localhost:3000/callback. Google permet http:// pas seulement https://) pour les URI localhost. Si vous modifiez votre port de développement, n'oubliez pas de mettre à jour l'URI enregistrée.
Ce sont deux domaines distincts et ils servent des objectifs différents. Les origines JavaScript autorisées sont utilisées pour les flux OAuth côté navigateur (flux implicite, services d'identité Google). Les URI de redirection autorisées sont utilisées pour les flux de code d'autorisation côté serveur. L'ajout d'une URI aux origines JavaScript ne résoudra PAS un problème. uri_de_redirection_introuvable erreur - vous devez l'ajouter au champ des URI de redirection. Un client Google OAuth peut avoir jusqu'à 100 URI de redirection enregistrées.
Erreur 400 : politique_admin_appliquée
Cette erreur n'est pas un bug dans votre code. Il s'agit d'une politique organisationnelle appliquée par un super administrateur Google Workspace. Un développeur ordinaire ne peut pas la corriger seul.
Le message d'erreur exact
Erreur 400 : admin_policy_enforced
Votre compte Google ne peut pas être utilisé pour l'autorisation en raison des
règlements de votre organisation. Contactez votre administrateur pour plus d'informations.
error=admin_policy_enforced
Cause
Un super administrateur Google Workspace a restreint les applications tierces ou les champs d'application OAuth auxquels les utilisateurs de l'organisation peuvent accorder l'accès. Ceci est configuré via Contrôles d'API Dans la console d'administration Google. Lorsqu'une application n'est pas sur la liste approuvée, tous les utilisateurs de cet espace de travail recevront cette erreur lorsqu'ils tenteront de l'autoriser, quel que soit le statut de vérification de l'application.
Ceci est un conformité et contrôle de sécurité, pas une mauvaise configuration côté développeur. La résolution correcte est toujours côté administrateur.
Corriger (côté admin uniquement)
Un utilisateur qui rencontre politique_admin_appliquée ne peuvent pas le résoudre eux-mêmes. Ils doivent contacter leur administrateur principal Google Workspace et demander que l'application OAuth spécifique soit marquée comme approuvée. Si l'utilisateur est l'administrateur, il peut suivre les étapes ci-dessus. Si le domaine impose une politique stricte "Autoriser des applications spécifiques", l'application doit d'abord être explicitement ajoutée à la liste approuvée avant de pouvoir être définie comme approuvée.
Si vous développez des outils internes et souhaitez éviter complètement le consentement OAuth par utilisateur, un compte de service avec délégation à l'échelle du domaine est l'alternative - consultez nos Compte de service Gmail et guide DWD.
accès_refusé & " Cette application est bloquée " (application non vérifiée)
Les utilisateurs voient un écran "Cette application est bloquée" ou reçoivent accès_refusé dans le rappel OAuth. Celle-ci a plusieurs causes profondes selon que votre application est encore en mode Test ou qu'elle cible des étendues restreintes.
Le message d'erreur exact
Accès bloqué : [Nom de votre application] n'a pas terminé le processus de vérification de Google
error=access_denied
-- ou --
Cette application est bloquée.
Cette application a tenté d'accéder à des informations sensibles de votre compte Google.
Contactez le développeur pour plus d'informations.
Causes
Tant que votre application OAuth est dans le statut de publication " Test ", seuls les utilisateurs explicitement ajoutés en tant qu'utilisateurs de test peuvent l'autoriser. Tout autre utilisateur recevra immédiatement un accès refusé.
Le mode test est limité à 100 utilisateurs uniques à la fois. Une fois que vous atteignez 100, les nouveaux utilisateurs ne pourront pas autoriser l'application, même s'ils sont ajoutés.
Des scopes tels que gmail.modifier ou gmail.envoyer sont des champs d'action sensibles. Les applications qui les demandent doivent suivre le processus de vérification des applications de Google avant que les utilisateurs réels ne puissent y accéder.
Un petit nombre de scopes (par exemple, l'accès complet à Gmail) sont restreints et nécessitent un audit de sécurité tiers (CASA) en plus de la vérification.
Réparer
grant invalide : "reconnectez votre compte Gmail"
Le erreur d'octroi non valide de l'API Gmail L'erreur est l'une des plus déroutantes en production – elle se manifeste silencieusement pour un sous-ensemble d'utilisateurs et nécessite un nouveau flux OAuth pour être résolue. Comprendre le cycle de vie du jeton de rafraîchissement est la clé pour la gérer correctement.
Le message d'erreur exact
{"error": "invalid_grant", "error_description": "Le jeton a expiré ou a été révoqué."}
-- ou --
{"error": "invalid_grant", "error_description": "Mauvaise requête"}
Cause : le cycle de vie du jeton d'actualisation
Correction : ré-autoriser avec access_type=offline + prompt=consent
from google_auth_oauthlib.flow import Débit
flux = Flow.from_client_secrets_file(
'client_secrets.json',
scopes=['https://www.googleapis.com/auth/gmail.readonly'],
uri_redirection=URI_REDIRECTION
)
# access_type=offline → obtenir un jeton d'actualisation
# prompt=consent → impose un nouveau consentement, renvoie toujours un nouveau jeton d'actualisation
auth_url, état = écoulement.autorisation_url(
type_d'accès='hors ligne',
invite'consentement'
)
# Enregistrer le NOUVEAU refresh_token fourni dans la réponse
L'ancien jeton # n'est désormais plus valide — mettez à jour votre base de donnéesPour éviter grant_invalide en production : toujours utiliser type_accès=hors_ligne et consentement lors de l'initiation du flux OAuth, mettez à jour votre jeton de rafraîchissement stocké chaque fois que l'utilisateur réautorise, détectez grant_invalide erreurs et déclenchez une interface utilisateur de réautorisation élégante (une invite " reconnectez votre compte Gmail "), et sortez votre application du mode Test pour obtenir des jetons permanents.
L'écran de consentement OAuth ne s'affiche pas dans la Google Cloud Console
Ceci est la requête de recherche avec le plus grand volume dans ce cluster (plus de 390 recherches par mois). La page " Écran de consentement OAuth " semble avoir disparu de la console Google Cloud pour de nombreux développeurs en 2024-2026 en raison d'une refonte de l'interface utilisateur. Elle n'a pas été supprimée, elle a été déplacée.
Symptôme
Vous ouvrez la console Google Cloud et accédez à API et services, mais l'élément de menu "Écran de consentement OAuth" est manquant ou cliquer dessus vous redirige vers un nouvel "Aperçu d'OAuth" page qui affiche un tableau de bord récapitulatif au lieu du formulaire de configuration attendu.
Causes
Réparez (étape par étape)
https://console.cloud.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID. Ce lien profond contourne la page de présentation et va directement à la configuration de l'écran de consentement. Pour un guide complet de chaque champ de configuration, de la sélection du type d'utilisateur et du plafond de 100 utilisateurs pour les tests, consultez notre Guide de configuration de l'écran de consentement OAuth.
Des semaines de vérification.
Utilisez La clé d'Unipile et commencez maintenant.
Ne perdez pas de clients en attendant les avis Google. Connectez les comptes Gmail en 5 minutes grâce à nos identifiants développeur pré-vérifiés.
portée_invalide
Une faute de frappe dans l'URL du champ d'application ou une API désactivée entraînera le rejet de la demande d'autorisation entière par Google avant toute interaction utilisateur.
Le message d'erreur exact
{"erreur": "scope_invalide",
"description_erreur": "Certains des champs d'application demandés étaient invalides.
{valide=[https://mail.google.com/], invalide=[gmail.readonly]}"}
-- ou sur l'URL de l'écran de consentement --
erreur=scope_invalide&description_erreur=Certains+des+champs+dapplication+demands+taient+invalides
Cause
Deux causes profondes courantes : (1) la valeur de portée est un nom court comme gmail.lecture seule au lieu de l'URL complète https://www.googleapis.com/auth/gmail.readonly, soit (2) l'API Gmail (ou toute autre API Google que vous ciblez) n'est pas activée dans le projet Google Cloud.
Portées courantes de Gmail et leurs URL correctes
| URL de portée (utilisez l'URL complète) | Ce que cela permet | Type |
|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Lire tous les messages et fils de discussion | Sensible |
| https://www.googleapis.com/auth/gmail.send | Envoyer un e-mail au nom de l'utilisateur | Sensible |
| https://www.googleapis.com/auth/gmail.modify | Lire, composer, envoyer, supprimer des fils | Sensible |
| https://mail.google.com/ | Accès complet à la boîte aux lettres (IMAP/SMTP) | Accès restreint |
| https://www.googleapis.com/auth/userinfo.email | Lire uniquement l'adresse e-mail de l'utilisateur | De base |
Réparer
https://www.googleapis.com/auth/ ou https://mail.google.com/). N'utilisez jamais la forme abrégée comme gmail.lecture seule.
"Google n'a pas vérifié cette application" et le plafond de 100 utilisateurs
L'écran d'avertissement " Google n'a pas vérifié cette application " apparaît lorsqu'une application non vérifiée demande des scopes sensibles ou restreints. Bien que les utilisateurs puissent continuer en cliquant sur " Avancé " puis sur " Accéder à [nom de l'application] (dangereux) ", cela ne convient pas à la production, et le mode test limite votre application à 100 utilisateurs uniques au total.
Cause
Lorsque votre application demande des portée sensibles (comme gmail.lecture seule ou gmail.envoyer), Google affiche cet écran d'avertissement à tous les utilisateurs jusqu'à ce que vous ayez terminé l'examen de vérification. Pour les étendues restreintes, vous devez également passer un audit de sécurité tiers (CASA Tier 2).
Lorsque le statut de publication est "En test" (Testing), cet écran d'avertissement s'affiche également pour les utilisateurs de test, et le nombre total d'utilisateurs de test autorisés est limité à 100. Les jetons pour les utilisateurs de test expirent après 7 jours.
Réparer
https://mail.google.com/en complément CASA Niveau 2 évaluation de sécurité par un évaluateur approuvé par Google.
Ces erreurs disparaissent lorsque le projet OAuth est déjà certifié
L'écran "Google n'a pas vérifié cette application", le plafond de 100 utilisateurs et l'expiration du jeton de 7 jours en mode Test sont tous des symptômes de posséder et gérer votre propre projet Google Cloud. Un intermédiaire technique indépendant qui agit au nom de chaque utilisateur authentifié - et a déjà terminé la certification CASA de niveau 2 - supprime l'intégralité de cette charge de votre côté. Vos utilisateurs autorisent une seule fois ; le cycle de vie des jetons, la conformité des portée et la re-vérification sont gérés au niveau de la plateforme.
Ceci n'est pas une solution de contournement pour l'examen de sécurité de Google. Unipile a terminé indépendamment la CASA Tier 2 et n'est affilié, approuvé ou sponsorisé par Google.
Intégrer sur OAuth Google déjà certifiéComment éviter cette classe entière d'erreurs Google OAuth
En examinant les 7 erreurs Google OAuth de ce guide, un schéma se dégage. Chacune d'entre elles provient de la même source : la gestion manuelle de votre propre projet Google Cloud et de sa configuration OAuth. Ces erreurs Google OAuth ne sont pas aléatoires – elles sont les conséquences structurelles de la possession d'un projet OAuth non vérifié, des incompatibilités d'URI de redirection et des échecs de rotation de jetons jusqu'au plafond de 100 utilisateurs et aux rejets de l'écran de consentement.
Il existe une autre façon. En utilisant un intermédiaire technique indépendant qui agit au nom de chaque utilisateur authentifié - qui a déjà terminé la revue de vérification de Google et la certification de sécurité CASA de niveau 2 - élimine chacun de ces modes de défaillance de votre responsabilité. La comparaison ci-dessous montre exactement quelles erreurs disparaissent et quelle infrastructure Unipile gère à la place. Voir le Documentation Unipile OAuth Google pour le guide d'intégration complet.
Chaque erreur dans ce guide : à qui appartient la correction ?
Les 7 erreurs Google OAuth abordées ci-dessus partagent une cause commune : vous possédez le projet Google Cloud, vous possédez donc tous les modes d'échec. Voici un aperçu côte à côte de ce que cela signifie en pratique.
La distinction clé : Unipile a déjà passé avec succès l'examen de sécurité de Google et l'évaluation CASA de niveau 2 pour les connexions qu'elle négocie en votre nom. Il ne s'agit pas d'une solution de contournement pour l'examen de sécurité de Google - Unipile l'a déjà passé. Vos utilisateurs obtiennent un écran de consentement clair (pas d'avertissement "application non vérifiée"), votre application est déployée immédiatement, et vous pouvez poursuivre votre propre vérification Google Cloud en parallèle sans aucune pression de délais de production.
Note de conformité : Unipile est un intermédiaire technique indépendant, non affilié, approuvé ou sponsorisé par Google. Le client OAuth Google d'Unipile est certifié CASA Tier 2, permettant à vos utilisateurs d'autoriser l'accès à Gmail sans avertissement "application non vérifiée" pour les connexions traitées par Unipile. Il ne s'agit pas d'une solution de contournement pour l'examen de sécurité de Google – Unipile l'a déjà passé pour les connexions qu'il traite. au nom de chaque utilisateur authentifié. Les utilisateurs peuvent révoquer l'accès à tout moment via la page des autorisations de leur compte Google.
FAQ sur les erreurs Google OAuth
Réponses aux questions les plus courantes sur les erreurs OAuth de Google et les erreurs de l'API Gmail, couvrant le cycle de vie des jetons, les politiques d'administration, les URI de redirection et la configuration de la console Google Cloud.
politique_admin_appliquée signifie qu'un super administrateur Google Workspace a bloqué votre application ou les champs d'application OAuth spécifiques qu'elle demande, afin que les utilisateurs de cette organisation ne puissent pas les autoriser. Il s'agit d'une politique de contrôle d'accès organisationnel, et non d'un bug dans votre code. La solution nécessite une action de la part du super administrateur Workspace dans la Google Admin Console sous Sécurité > Contrôles d’API > Gérer l’accès aux applications tierces.
Non. Un utilisateur standard ne peut pas résoudre le problème admin_policy_enforced. Seul un administrateur Google Workspace superadministrateur peut résoudre cette erreur en marquant l'application comme de confiance dans la console d'administration. L'utilisateur concerné doit contacter son administrateur informatique ou son super administrateur Workspace et demander que l'application OAuth spécifique soit ajoutée à la liste approuvée.
Le uri_de_redirection_introuvable sur localhost se produit lorsque l'URI que vous enregistrez dans la Google Cloud Console ne correspond pas exactement à l'URI utilisée par votre serveur de développement local. Par exemple, l'enregistrement http://localhost:3000/callback mais fonctionnant sur le port 3001, ou oubliant une barre oblique finale. Google permet http:// pas seulement https://) pour les URI localhost. Enregistrez l'URI exacte que votre serveur local utilise, y compris le numéro de port correct.
Non. Les origines JavaScript autorisées et les URI de redirection autorisés sont deux champs distincts. Les origines JavaScript sont utilisées uniquement pour les flux OAuth côté navigateur. Pour corriger uri_de_redirection_introuvable, vous devez ajouter l'URI à la URIs de redirection autorisés champ, pas aux origines JavaScript.
Un seul client Google OAuth 2.0 peut avoir jusqu'à 100 URI de redirection autorisés enregistré. Cela vous permet d'enregistrer des URI pour différents environnements (développement local, staging, production) et différents chemins de rappel au sein du même client.
Si votre application est en Test du statut de publication, les jetons d'actualisation de Google expirent après 7 jours quelle que soit l'utilisation. C'est intentionnel pour les applications non vérifiées. Passez au statut Production en cliquant sur Publier l'application sur la page de l'écran OAuth de consentement pour obtenir des jetons de longue durée. En production, les jetons d'actualisation restent valides tant que l'utilisateur utilise votre application au moins une fois tous les 6 mois. Pour une alternative gérée, consultez notre solution Gmail API gérée.
Google révoque les jetons d'actualisation qui n'ont pas été utilisés pendant 6 mois (environ 180 jours). Les jetons sont également révoqués lorsque : l'utilisateur modifie le mot de passe de son compte Google, l'utilisateur révoque l'accès d'une application dans les paramètres de sécurité de son compte Google, vous ré-autorisez avec des champs d'application différents, ou le nombre total de jetons d'actualisation pour une paire utilisateur-application unique dépasse 50 (les plus anciens sont révoqués en premier). Pour une vision complète de la création d'intégrations d'e-mails robustes, consultez notre Guide complet de l'API d'e-mail.
Google a redessiné la Cloud Console en 2024. La configuration de l'écran de consentement OAuth se trouve maintenant dans APIs et services > Présentation d'OAuth. Cliquer Modifier l'application ou utilisez les onglets Branding, Audience et Scopes. Vérifiez également : vous avez besoin Rôle d'éditeur ou de propriétaire sur le projet (le visualiseur ne peut pas accéder au formulaire), et assurez-vous que vous êtes sur le bon projet en utilisant le sélecteur de projet en haut de la console.
Vous rencontrez toujours une erreur Google OAuth qui n'est pas listée ici ? Évitez le débogage et laissez Unipile gérer l'OAuth Gmail pour vous.
Démarrer
FR 
EN 
ES 
DE 
IT 
BR 
NL 
PL 
TR