Por que os Comandos de Barra do Bot do Discord Demoram Horas para Registrar Globalmente

Você adicionou um novo comando de barra ao seu bot do Discord, mas ele não aparece para nenhum usuário fora do seu servidor de teste. Esse atraso ocorre porque o Discord usa um cache global de comandos que é atualizado em um cronograma contínuo. A plataforma não envia alterações de comando instantaneamente para todos os servidores. Este artigo explica o motivo técnico do atraso, como funciona o processo de registro e o que você pode fazer para acelerar ou contornar a espera.

Por que o Discord Adia Atualizações de Comandos de Barra Globais

O Discord opera uma infraestrutura distribuída com centenas de servidores ao redor do mundo. Quando você registra um comando de barra global através da API ou do Developer Portal, o Discord não envia essa alteração para todos os servidores ao mesmo tempo. Em vez disso, a plataforma coloca o comando em uma fila e atualiza seu cache global de comandos em um cronograma contínuo. Essa atualização do cache geralmente ocorre a cada uma ou duas horas, embora o intervalo exato possa variar com base na carga do servidor e no número de atualizações pendentes.

O atraso é proposital. A propagação instantânea exigiria que o Discord sincronizasse dados de comando em todos os seus servidores simultaneamente, o que criaria um pico de carga massivo e aumentaria o risco de falhas parciais. Ao agrupar atualizações e aplicá-las gradualmente, o Discord mantém a estabilidade e garante que todos os servidores recebam a mesma lista de comandos sem conflitos.

Comandos de Guild vs Comandos Globais

O Discord oferece dois tipos de registro de comandos de barra: comandos de guild e comandos globais. Comandos de guild são registrados para um servidor específico e aparecem instantaneamente. Comandos globais são registrados para todos os servidores e estão sujeitos ao atraso de atualização do cache. Se você está desenvolvendo ou testando um bot, sempre use comandos de guild primeiro para verificar a funcionalidade antes de enviar o comando globalmente.

Passos para Verificar e Acelerar o Registro de Comandos Globais

1. Verifique o registro do comando no Developer Portal
   Abra o Discord Developer Portal, selecione seu aplicativo e vá para a seção Slash Commands. Confirme que o comando aparece na lista. Se não aparecer, sua solicitação de registro falhou. Verifique seu token do bot e a URL do endpoint da API.
2. Verifique o tempo de atualização do cache de comandos globais
   O Discord não fornece um endpoint público para ver o horário exato de atualização do cache. Como alternativa, anote o horário em que registrou o comando. Aguarde pelo menos uma hora. Se o comando ainda estiver ausente após duas horas, investigue limites de taxa ou erros de API.
3. Use comandos de guild para testes imediatos
   Registre o comando como um comando de guild no seu servidor de teste. Use o endpoint PATCH /applications/{app_id}/guilds/{guild_id}/commands com seu token do bot. O comando aparecerá em segundos. Após testar, você pode registrá-lo globalmente e remover a versão de guild.
4. Verifique os cabeçalhos de limite de taxa
   Ao registrar um comando via API, examine os cabeçalhos de resposta para X-RateLimit-Remaining e X-RateLimit-Reset. Se você vir um limite zero ou um tempo de reset longo, atingiu um limite de taxa. Afaste-se e aguarde o reset antes de tentar novamente.
5. Exclua e registre novamente o comando
   Se o comando não aparecer após duas horas, exclua-o através do Developer Portal ou da API e registre-o novamente. Essa ação força uma nova entrada na fila. Não repita isso mais de uma vez por hora para evitar limites de taxa.

Se os Comandos de Barra Ainda Não Aparecerem Após Várias Horas

Bot foi adicionado a servidores antes do registro do comando

Se você adicionou seu bot a servidores antes de registrar qualquer comando de barra, esses servidores podem ter armazenado em cache uma lista vazia de comandos. O Discord geralmente atualiza esse cache em até 24 horas. Para forçar uma atualização, remova o bot do servidor e o reconvide com o escopo applications.commands.

Limites de taxa bloquearam seu registro

O Discord impõe um limite de taxa de 200 atualizações de comandos globais por dia por aplicativo. Se você excedeu esse limite, as solicitações de registro subsequentes são descartadas silenciosamente. Verifique a resposta da API para um código de status 429. Aguarde até o próximo dia calendário para registrar novos comandos.

Conflito de nome de comando com outro bot

Se outro bot no mesmo servidor já usa exatamente o mesmo nome de comando de barra, o Discord pode suprimir seu comando para evitar ambiguidade. Escolha um nome único ou prefixe seu comando com o nome do seu bot. Por exemplo, use /meubot-ajuda em vez de /ajuda.

Registro de Comandos Globais vs de Guild: Principais Diferenças

Item	Comandos Globais	Comandos de Guild
Atraso de aparecimento	1–2 horas (atualização de cache)	Instantâneo (segundos)
Escopo	Todos os servidores onde o bot está presente	Apenas o servidor especificado
Limite de taxa	200 atualizações por dia por app	Sem limite diário, mas limite de 100 comandos por guild
Caso de uso	Comandos de produção para todos os usuários	Desenvolvimento, testes ou comandos específicos de servidor

O Discord atrasa intencionalmente o registro de comandos globais para manter a estabilidade do sistema em sua rede distribuída. A janela de atualização de cache de uma a duas horas é normal e não é um bug. Para testes imediatos, sempre use comandos de guild. Se você precisa que um comando global apareça mais rápido, planeje seu registro em torno do ciclo de atualização e evite atingir o limite diário de 200 atualizações. Após a atualização do cache, todos os servidores verão o novo comando sem qualquer ação adicional.