Corrigir Erro ‘Escopo Inválido’ no OAuth do Bot do Discord Mesmo com Escopo Selecionado

Ao configurar um bot do Discord, você pode encontrar uma página de erro que diz “Escopo Inválido” após autorizar o bot pelo fluxo OAuth2, mesmo tendo selecionado cuidadosamente os escopos corretos no Portal do Desenvolvedor do Discord. Esse erro impede o bot de entrar no servidor e bloqueia qualquer funcionalidade. A causa raiz é quase sempre uma incompatibilidade entre os escopos listados na URL OAuth2 e os escopos que o aplicativo do bot está realmente configurado para usar. Este artigo explica exatamente por que essa incompatibilidade ocorre e fornece uma correção passo a passo para resolvê-la.

Por que o Discord Retorna “Escopo Inválido” Durante a Autorização OAuth

O erro “Escopo Inválido” ocorre porque o sistema OAuth2 do Discord valida os escopos na URL de autorização em relação à configuração do aplicativo do bot. Cada escopo incluído na URL deve ser um que o aplicativo tenha permissão para solicitar. Se você incluir um escopo que não está ativado para o bot, o Discord rejeita toda a solicitação.

Existem três razões principais para isso acontecer:

1. Escopo Não Ativado no Portal do Desenvolvedor

A causa mais comum é selecionar um escopo no Gerador de URL OAuth2 que não está realmente ativado para o bot. Por exemplo, o escopo bot deve ser explicitamente ativado. O escopo applications.commands também precisa ser ativado para comandos de barra. Se você selecionar esses escopos, mas eles não estiverem ativados nas configurações do Bot, a validação falha.

2. Intent de Gateway Privilegiado Não Correspondente ao Escopo

Intents de Gateway Privilegiados como Server Members Intent, Message Content Intent e Presence Intent são separados dos escopos OAuth2. Ativar um intent nas configurações do Bot não adiciona automaticamente o escopo OAuth2 correspondente. Se o código do seu bot requer o escopo guilds.members.read, mas você apenas ativou o Server Members Intent, o escopo está faltando na URL. O erro aparece porque o escopo não está na URL.

3. URI de Redirecionamento Incorreto

Se sua URL OAuth2 inclui um URI de redirecionamento que não está registrado no Portal do Desenvolvedor, o Discord pode retornar um erro genérico que inclui “Escopo Inválido” na mensagem. Isso acontece porque a validação do redirecionamento ocorre antes da validação do escopo. Corrigir o URI de redirecionamento resolve o problema.

Passos para Corrigir o Erro “Escopo Inválido” ao Autorizar um Bot do Discord

Siga estes passos em ordem. Não pule nenhum passo.

1. Abra o Portal do Desenvolvedor do Discord e selecione o aplicativo do bot
   Vá para o Portal do Desenvolvedor do Discord em https://discord.com/developers/applications. Faça login com a conta que possui o bot. Clique no aplicativo que está retornando o erro.
2. Vá para a página de configurações do Bot e verifique os Intents de Gateway Privilegiados
   Na barra lateral esquerda, clique em “Bot”. Role até a seção Privileged Gateway Intents. Verifique quais intents estão ativados. Anote-os. Por exemplo, se você precisa que o bot leia o conteúdo das mensagens, certifique-se de que “Message Content Intent” esteja ativado. Se precisar que ele veja todos os membros do servidor, ative “Server Members Intent”.
3. Vá para a página OAuth2 > URL Generator
   Na barra lateral esquerda, clique em “OAuth2” e depois em “URL Generator”. É aqui que você monta a URL de autorização.
4. Selecione os escopos corretos na seção Scopes
   Na seção Scopes, selecione os escopos que seu bot realmente precisa. Os escopos mais comuns são:

   – bot: Necessário para qualquer bot que entre em um servidor.
   – applications.commands: Necessário para comandos de barra.
   – guilds: Permite que o bot veja os servidores em que está.
   – guilds.members.read: Necessário se você ativou o Server Members Intent.
   – messages.read: Necessário se você ativou o Message Content Intent.

   Se você ativou um intent privilegiado no Passo 2, também deve selecionar o escopo correspondente aqui. Por exemplo, se você ativou o Server Members Intent, selecione guilds.members.read. Se ativou o Message Content Intent, selecione messages.read.

5. Defina o URI de redirecionamento corretamente
   Na seção Redirects, insira a URL exata que seu aplicativo usa para callbacks OAuth2. Se você não tem um redirecionamento personalizado, deixe em branco. Se usa um redirecionamento personalizado, clique em “Add Redirect” e digite a URL completa. Para testes, você pode usar https://localhost. Não inclua uma barra no final, a menos que a URL exija.
6. Gere a URL e copie-a
   Na parte inferior da página URL Generator, clique em “Copy” para copiar a URL gerada. Não modifique a URL manualmente. Qualquer alteração manual pode introduzir um escopo inválido.
7. Abra a URL em uma nova aba ou janela do navegador
   Cole a URL em uma nova aba do navegador. Será solicitado que você selecione um servidor. Escolha o servidor para o qual deseja que o bot entre. Clique em “Authorize”. O erro não deve mais aparecer.
8. Se o erro persistir, verifique o código do bot quanto aos requisitos de escopo
   Algumas bibliotecas de bot exigem que você especifique escopos no código. Por exemplo, discord.js usa o construtor Client com um array intents. Se seu código solicitar um escopo que não está na URL, adicione esse escopo ao URL Generator. Escopos comuns ausentes são guilds e guilds.members.read.

Se o Discord Ainda Retornar “Escopo Inválido” Após a Correção Principal

O erro aparece apenas em navegadores móveis

Navegadores móveis às vezes armazenam em cache redirecionamentos OAuth2 antigos. Limpe o cache do navegador ou use uma janela de navegação privada. Em seguida, copie a URL do Portal do Desenvolvedor novamente e cole-a na janela privada.

O código do bot usa um escopo diferente do que está na URL

Verifique o código-fonte do seu bot. No discord.py, o construtor Bot aceita um parâmetro intents. Se você definiu intents.message_content = True, deve adicionar o escopo messages.read à URL. Se definiu intents.members = True, adicione guilds.members.read. Atualize o URL Generator com o escopo ausente e gere uma nova URL.

O aplicativo do bot tem um proprietário diferente de quem está autorizando

Apenas o proprietário do aplicativo do bot pode autorizar o bot pela primeira vez. Se você está tentando autorizar um bot que não possui, verá um erro. A validação do escopo ainda é executada, mas a mensagem de erro pode dizer “Escopo Inválido” em vez de um erro de permissão. Certifique-se de estar logado na conta que possui o aplicativo.

Escopos OAuth2 para Bots do Discord: Escopos Comuns vs Escopos Privilegiados

Escopo	O Que Faz	Requer Intent Privilegiado?
bot	Permite que o bot entre em um servidor e execute ações básicas	Não
applications.commands	Permite que o bot registre e use comandos de barra	Não
guilds	Permite que o bot veja informações básicas do servidor	Não
guilds.members.read	Permite que o bot leia listas de membros e eventos de entrada/saída	Sim — Server Members Intent deve estar ativado
messages.read	Permite que o bot leia o conteúdo das mensagens	Sim — Message Content Intent deve estar ativado

Quando você ativa um intent privilegiado nas configurações do Bot, também deve adicionar o escopo correspondente à URL OAuth2. Se não fizer isso, o escopo estará faltando e o Discord retornará “Escopo Inválido”.

Agora você pode corrigir o erro “Escopo Inválido” combinando os escopos no URL Generator com os intents ativados nas configurações do Bot e os escopos exigidos pelo código do seu bot. Sempre gere uma nova URL a partir do Portal do Desenvolvedor em vez de reutilizar uma antiga. Se o seu bot precisar de comandos de barra e leitura de mensagens, selecione ambos applications.commands e messages.read na lista de escopos. Essa abordagem impede que o erro retorne.