LinkedIn
Instagram
WhatsApp
Telegrama
Gmail
Perspectivas
Google Agenda
Participe da comunidade do SlackErros Comuns do Google OAuth e da API do Gmail (e Como Corrigir Cada Um)
Todo desenvolvedor que integrar o Gmail ou o Google Agenda com o Google OAuth encontrará pelo menos um desses erros do Google OAuth. Este guia consolida todos os 7 erros comuns do Google OAuth em um só lugar – com a causa exata e a correção passo a passo para cada um deles. Entender esses erros do Google OAuth economizará horas de depuração.
# Troca de tokens do Google OAuth
import solicitações
token_resposta = requests.post(
"https://oauth2.googleapis.com/token",
dados={
"código": código_de_autorização,
"id_do_cliente": ID_DO_CLIENTE,
"client_secret": CLIENT_SECRET,
"redirect_uri": URI_DE_REDIRECIONAMENTO,
"grant_type": "código_de_autorização"
}
)Referência rápida: todos os erros do Google OAuth em um piscar de olhos
Uma tabela resumida de todos os 7 erros do Google OAuth abordados neste guia - estágio em que ocorre, causa raiz e o link de correção rápida para a seção detalhada abaixo. Marque esta tabela como referência ao depurar erros do Google OAuth em desenvolvimento ou produção.
| Mensagem de erro | Palco | Causa raiz | Conserto rápido |
|---|---|---|---|
| redirect_uri_mismatch | Authorization | A URI de redirecionamento na sua solicitação não corresponde exatamente a uma registrada no Google Cloud Console | Conserte |
| administrador_política_imposta | Authorization | Um superadministrador do Workspace restringiu quais apps ou escopos OAuth os usuários na organização podem conceder acesso. | Conserte |
| acesso_negado | Authorization | O aplicativo está em modo de teste e o usuário não é um usuário de teste, ou o aplicativo solicita escopos restritos sem verificação | Conserte |
| concessão_inválida | Atualização de token | Token de atualização expirado, revogado ou usado mais de uma vez (código de autenticação de uso único) | Conserte |
| Tela de consentimento ausente | Console do Google Cloud | A nova interface do Google Cloud moveu a tela de consentimento OAuth; também exige a função de Proprietário/Editor no projeto | Conserte |
| escopo_inválido | Authorization | Erro na URL do escopo ou a API do Google correspondente não está habilitada no projeto | Conserte |
| O Google não verificou | Authorization | O app usa escopos restritos/sensíveis, mas não completou a verificação do Google. O modo de teste tem limite de 100 usuários. | Conserte |
Erro 400: redirect_uri_mismatch
Este é o erro OAuth do Google mais comum para desenvolvedores que configuram uma nova integração. Ele ocorre durante a etapa de autorização - antes que qualquer token seja emitido.
A mensagem de erro exata
Erro 400: redirect_uri_mismatch
O URI de redirecionamento na solicitação não corresponde a um URI de redirecionamento registrado.
error=redirect_uri_mismatch
Causa
Google compara o redirect_uri parâmetro que você passa na sua URL de autorização com a lista de URIs de redirecionamento autorizadas registradas no seu cliente OAuth no Console do Google Cloud. Mesmo uma diferença de um único caractere - uma barra final, http vs https, ou uma porta diferente - aciona este erro.
Corrigir (passo a passo)
https://yourapp.com/oauth/callback. O valor deve ser idêntico, caractere por caractere, incluindo esquema, porta e barra final.
redirect_uri o valor que você passa para o endpoint de autorização e para o endpoint de troca de tokens são idênticos.
redirect_uri_mismatch em localhost
Durante o desenvolvimento local, registre o URI exato do localhost que você usa - por exemplo http://localhost:3000/callback. O Google permite http:// (não apenas https://) para URIs localhost. Se você alterar sua porta de desenvolvimento, lembre-se de atualizar a URI registrada.
Estes são dois campos separados e servem a propósitos diferentes. Origens JavaScript autorizadas são usadas para fluxos OAuth do lado do navegador (fluxo implícito, Google Identity Services). URIs de redirecionamento autorizadas são usadas para fluxos de código de autorização do lado do servidor. Adicionar uma URI às origens JavaScript NÃO corrigirá um redirect_uri_mismatch erro - você deve adicioná-lo ao campo URIs de redirecionamento. Um cliente OAuth do Google pode ter até 100 URIs de redirecionamento registradas.
Erro 400: política de administrador aplicada
Este erro não é um bug no seu código. É uma política organizacional imposta por um super administrador do Google Workspace. Um desenvolvedor comum não consegue corrigi-lo sozinho.
A mensagem de erro exata
Erro 400: admin_policy_enforced
A conta Google não pode ser usada para autorização devido às políticas da sua organização. Contate seu administrador para mais informações.
error=admin_policy_enforced
Causa
Um superadministrador do Google Workspace restringiu quais aplicativos de terceiros ou escopos OAuth os usuários na organização podem conceder acesso. Isso é configurado via Controles da API no Google Admin Console. Quando um aplicativo não está na lista de aprovados, todo usuário desse Workspace receberá este erro ao tentar autorizá-lo, independentemente do status de verificação do aplicativo.
Isto é um conformidade e controle de segurança, não uma má configuração do lado do desenvolvedor. A resolução correta é sempre do lado do administrador.
Correção (apenas lado do administrador)
Um usuário que encontra administrador_política_imposta não conseguem resolver por conta própria. Eles precisam entrar em contato com o superadministrador do Google Workspace e solicitar que o aplicativo OAuth específico seja marcado como Confiável. Se o usuário for o administrador, ele pode seguir as etapas acima. Se o domínio aplicar uma política restrita de "Permitir aplicativos específicos", o aplicativo deverá primeiro ser explicitamente adicionado à lista de aprovados antes de poder ser definido como Confiável.
Se você estiver criando ferramentas internas e quiser evitar completamente o consentimento OAuth por usuário, uma conta de serviço com Delegação em Nível de Domínio é a alternativa - veja nosso Conta de serviço do Gmail e guia DWD.
acesso_negado & "Este aplicativo está bloqueado" (aplicativo não verificado)
Os usuários veem uma tela "Este aplicativo está bloqueado" ou recebem acesso_negado no callback do OAuth. Esta tem múltiplas causas raiz dependendo se o seu aplicativo ainda está no modo de teste ou se está visando escopos restritos.
A mensagem de erro exata
Acesso bloqueado: [Nome do seu aplicativo] não concluiu o processo de verificação do Google
erro=access_denied
-- ou --
Este app está bloqueado.
Este app tentou acessar informações sensíveis na sua Conta do Google.
Entre em contato com o desenvolvedor para mais informações.
Causas
Enquanto seu aplicativo OAuth estiver no status de publicação "Em teste", somente usuários explicitamente adicionados como testadores poderão autorizá-lo. Qualquer outra pessoa receberá imediatamente acesso negado.
O modo de teste é limitado a 100 usuários de teste exclusivos a qualquer momento. Quando você atinge 100, novos usuários não podem autorizar o aplicativo, mesmo que adicionados.
Escopos como gmail.modificar ou gmail.enviar são escopos sensíveis. Aplicativos que os solicitam devem concluir o processo de verificação de aplicativos do Google antes que usuários reais possam conceder acesso.
Um pequeno número de escopos (por exemplo, acesso completo ao Gmail) são Restritos e exigem uma auditoria de segurança de terceiros (CASA) além da verificação.
Consertar
invalid_grant: "reconecte sua conta do Gmail"
O API do Gmail: concessão inválida erro é um dos mais confusos em produção - ele falha silenciosamente para um subconjunto de usuários e requer um novo fluxo OAuth para recuperação. Entender o ciclo de vida do token de atualização é a chave para lidar com ele corretamente.
A mensagem de erro exata
{"error": "invalid_grant", "error_description": "O token expirou ou foi revogado."}
-- ou --
{"error": "invalid_grant", "error_description": "Requisição inválida"}
Causa: o ciclo de vida do token de atualização
Corrigir: reautorizar com access_type=offline + prompt=consent
from google_auth_oauthlib.flow import Fluxo
fluxo = Flow.from_client_secrets_file(
'client_secrets.json',
escopos=['https://www.googleapis.com/auth/gmail.readonly'],
redirect_uri=REDIRECT_URI
)
# access_type=offline → obter um token de atualização
# prompt=consent → exige novo consentimento; retorna sempre um novo token de atualização
auth_url, estado = fluxo.url_de_autorizacao(
tipo_de_acesso='offline',
prompt='consentimento'
)
# Armazene o NOVO refresh_token da resposta
O token antigo # já não é válido — atualize seu banco de dadosPara evitar concessão_inválida em produção: sempre use access_type=offline e consentimento Ao iniciar o fluxo OAuth, atualize seu token de atualização armazenado toda vez que o usuário reautorizar, detecte concessão_inválida erros e acionar uma interface de reautorização graciosa (um prompt de "reconectar sua conta do Gmail"), e remover seu aplicativo do modo de teste para obter tokens permanentes.
A tela de consentimento do OAuth não aparece no Google Cloud Console
Esta é a consulta de pesquisa com o maior volume neste cluster (mais de 390 pesquisas mensais). A página "Tela de consentimento OAuth" parece ter desaparecido do Google Cloud Console para muitos desenvolvedores entre 2024 e 2026 devido a uma reformulação da interface do usuário. Ela não foi removida, apenas foi movida.
Sintoma
Você abre o Google Cloud Console e navega até APIs e Serviços, mas o item de menu "Tela de consentimento do OAuth" está faltando ou clicar nele redireciona você para uma nova "Visão Geral do OAuth" página que exibe um painel de resumo em vez do formulário de configuração esperado.
Causas
Corrigir (passo a passo)
https://console.cloud.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID. Este link direto ignora a página de visão geral e vai direto para a configuração da tela de consentimento. Para um guia completo sobre todos os campos de configuração, seleção de tipo de usuário e o limite de teste de 100 usuários, consulte nosso Guia de configuração da tela de consentimento do OAuth.
Semanas de verificação.
Uso Chave Unipile e comece agora.
Não perca clientes esperando pela avaliação do Google. Conecte contas do Gmail em 5 minutos com nossas credenciais de desenvolvedor pré-verificadas.
escopo_inválido
Um erro de digitação na URL do escopo ou uma API desabilitada fará com que o Google rejeite toda a solicitação de autorização antes que qualquer interação do usuário ocorra.
A mensagem de erro exata
{"erro": "invalid_scope",
"erro_descricao": "Alguns escopos solicitados eram inválidos.
{válidos=[https://mail.google.com/], inválidos=[gmail.readonly]}"}
-- ou na URL da tela de consentimento --
erro=invalid_scope&erro_descricao=Some+requested+scopes+were+invalid
Causa
Duas causas comuns: (1) o valor do escopo é um nome curto como gmail.somente leitura em vez do URL completo https://www.googleapis.com/auth/gmail.readonly, ou (2) a API do Gmail (ou qualquer outra API do Google que você esteja definindo) não está habilitada no projeto do Google Cloud.
Escopos comuns do Gmail e seus URLs corretos
| URL de escopo (use o URL completo) | O que permite | Tipo |
|---|---|---|
| https://www.googleapis.com/auth/gmail.readonly | Ler todas as mensagens e conversas | Sensível |
| https://www.googleapis.com/auth/gmail.send | Enviar e-mail em nome do usuário | Sensível |
| https://www.googleapis.com/auth/gmail.modify | Ler, compor, enviar, excluir threads | Sensível |
| https://mail.google.com/ | Acesso total à caixa de correio (IMAP/SMTP) | Restrito |
| https://www.googleapis.com/auth/userinfo.email | Leia apenas o endereço de e-mail do usuário | Básico |
Consertar
https://www.googleapis.com/auth/ ou https://mail.google.com/). Nunca use a forma curta como gmail.somente leitura.
"O Google não verificou este aplicativo" e o limite de 100 usuários
A tela de aviso "O Google não verificou este app" aparece quando um app não verificado solicita escopos sensíveis ou restritos. Embora os usuários possam prosseguir clicando em "Avançado" e depois em "Ir para [nome do app] (inseguro)", isso não é adequado para produção - e o modo de teste limita seu app a um total de 100 usuários únicos.
Causa
Quando seu aplicativo solicita escopos sensíveis (como gmail.somente leitura ou gmail.enviar), o Google exibe esta tela de aviso para todos os usuários até que você conclua a revisão de verificação. Para escopos restritos, você também precisa passar por uma auditoria de segurança de terceiros (CASA Nível 2).
Enquanto estiver em status de publicação de teste, esta tela de aviso também será exibida mesmo para usuários de teste, e o número total de usuários de teste permitidos é limitado a 100. Os tokens para usuários de teste expiram após 7 dias.
Consertar
https://mail.google.com/adicionalmente completar um CASA Nível 2 avaliação de segurança por um avaliador aprovado pelo Google.
Estes erros desaparecem quando o projeto OAuth já está certificado
A tela "O Google não verificou este aplicativo", o limite de 100 usuários e a expiração do token de 7 dias no modo de teste são todos sintomas de gerenciando e administrando seu próprio projeto do Google Cloud. Um intermediário técnico independente que atua em nome de cada usuário autenticado - e já completou a certificação CASA Tier 2 - remove toda essa sobrecarga do seu lado. Seus usuários autorizam uma vez; o ciclo de vida do token, a conformidade de escopo e a reverificação são gerenciados no nível da plataforma.
Isso não é uma solução alternativa para a análise de segurança do Google. A Unipile completou independentemente a CASA Nível 2 e não é afiliada, endossada ou patrocinada pelo Google.
Navio em Google OAuth já certificadoComo evitar toda essa classe de erros do Google OAuth
Olhando para todos os 7 erros do Google OAuth neste guia, um padrão emerge. Cada um deles origina-se da mesma raiz: gerenciar seu próprio projeto do Google Cloud e sua configuração OAuth manualmente. Esses erros do Google OAuth não são aleatórios - eles são consequências estruturais de ter um projeto OAuth não verificado, desde incompatibilidades de URI de redirecionamento e falhas na rotação de tokens até o limite de 100 usuários e rejeições da tela de consentimento.
Existe outra maneira. Usando um intermediário técnico independente que age em nome de cada usuário autenticado - que já completou a análise de verificação do Google e a certificação de segurança CASA Tier 2 - elimina todos esses modos de falha da sua responsabilidade. A comparação abaixo mostra exatamente quais erros desaparecem e qual infraestrutura a Unipile gerencia. Veja a Documentação do Google OAuth da Unipile para o guia de integração completo.
Todos os erros neste guia: quem é o dono da correção?
Os 7 erros do Google OAuth abordados acima compartilham uma raiz comum: você é o proprietário do projeto Google Cloud, portanto, você é o proprietário de todos os modos de falha. Aqui está uma análise lado a lado do que isso significa na prática.
A distinção chave: A Unipile já concluiu a revisão de segurança do Google e a avaliação CASA Tier 2 para as conexões que ela intermedia em seu nome. Esta não é uma solução alternativa para a revisão de segurança do Google - a Unipile já a passou. Seus usuários recebem uma tela de consentimento limpa (sem aviso de "aplicativo não verificado"), seu aplicativo é lançado imediatamente, e você pode prosseguir com sua própria verificação do Google Cloud em paralelo sem qualquer pressão de prazo de produção.
Nota de conformidade: Unipile é um intermediário técnico independente, não afiliado, endossado ou patrocinado pelo Google. O cliente OAuth do Google da Unipile possui certificação CASA Tier 2, permitindo que seus usuários autorizem o acesso ao Gmail sem um aviso de "aplicativo não verificado" para conexões intermediadas pela Unipile. Isso não é uma solução alternativa para a revisão de segurança do Google - a Unipile já a passou para as conexões que intermedia. em nome de cada usuário autenticado. Os usuários podem revogar o acesso a qualquer momento na página de permissões da sua Conta do Google.
Perguntas Frequentes sobre erros do Google OAuth
Respostas para as perguntas mais comuns sobre erros do OAuth do Google e erros da API do Gmail, cobrindo ciclo de vida do token, políticas de administrador, URIs de redirecionamento e configuração do Google Cloud Console.
administrador_política_imposta significa que um superadministrador do Google Workspace bloqueou seu aplicativo ou os escopos OAuth específicos que ele solicita para serem autorizados por usuários nessa organização. É uma política de controle de acesso organizacional, não um bug no seu código. A correção requer ação do superadministrador do Workspace no Google Admin Console em Segurança > Controles de API > Gerenciar acesso a aplicativos de terceiros.
Não. Um usuário comum não pode corrigir `admin_policy_enforced`. Somente um Google Workspace superadministrador pode resolver este erro marcando o aplicativo como Confiável no Admin Console. O usuário afetado precisa entrar em contato com seu administrador de TI ou administrador principal do Workspace e solicitar que o aplicativo OAuth específico seja adicionado à lista de aprovados.
O redirect_uri_mismatch no localhost ocorre quando a URI que você registra no Google Cloud Console não corresponde exatamente à URI que seu servidor de desenvolvimento local usa. Por exemplo, registrar http://localhost:3000/callback mas rodando na porta 3001, ou esquecendo uma barra final. O Google permite http:// (não apenas https://) para URIs de localhost. Registre o URI exato que seu servidor local usa, incluindo o número da porta correto.
Não. Origens JavaScript autorizadas e URIs de redirecionamento autorizados são dois campos separados. As origens JavaScript são usadas apenas para fluxos OAuth do lado do navegador. Para corrigir redirect_uri_mismatch, você deve adicionar a URI a URIs de redirecionamento autorizados campo, não às origens do JavaScript.
Um único cliente OAuth 2.0 do Google pode ter até 100 URIs de redirecionamento autorizados registrado. Isso permite que você registre URIs para diferentes ambientes (desenvolvimento local, staging, produção) e diferentes caminhos de callback dentro do mesmo cliente.
Se o seu aplicativo estiver em Testando status de publicação, tokens de atualização do Google expiram após 7 dias independentemente do uso. Isso é por design para aplicativos não verificados. Mova para o status Produção clicando Publicar App na página da tela de consentimento do OAuth para obter tokens de longa duração. Em Produção, os tokens de atualização permanecem válidos enquanto o usuário usar seu aplicativo pelo menos uma vez a cada 6 meses. Para uma alternativa gerenciada, visite nosso Solução gerenciada da API do Gmail.
O Google revoga tokens de atualização que não foram usados por 6 meses (aproximadamente 180 dias). Tokens também são revogados quando: o usuário altera a senha da Conta Google, o usuário revoga o acesso do aplicativo nas configurações de segurança da Conta Google, você se reautoriza com escopos diferentes, ou o total de tokens de atualização para um único par usuário-aplicativo excede 50 (os mais antigos são revogados primeiro). Para obter uma visão completa sobre como criar integrações de e-mail robustas, consulte nosso Guia completo da API de E-mail.
O Google redesenhou o Cloud Console em 2024. A configuração da tela de consentimento do OAuth agora está dentro APIs e Serviços > Visão geral do OAuth. Clicar Editar Aplicativo ou use as abas Branding, Audience e Scopes. Verifique também: você precisa Editor ou Proprietário no projeto (o visualizador não consegue acessar o formulário) e certifique-se de que está no projeto correto usando o seletor de projeto na parte superior do console.
Ainda encontrando um erro no Google OAuth que não está listado aqui? Pule a depuração e deixe a Unipile cuidar do OAuth do Gmail para você.
Crie já
BR 
EN 
FR 
ES 
DE 
IT 
NL 
PL 
TR