Moderação de guilda

Um banimento de guilda mantém uma conta fora de uma guilda e sobrevive à associação que ele remove. Remover um membro é uma operação separada com sua própria permissão, e Remover membro da guilda a define.

Toda rota aqui requer BAN_MEMBERS, que é uma permissão elevada. Em uma guilda cujo nível MFA seja elevado, todo solicitante, exceto o proprietário da guilda, também precisa de um autenticador multifator cadastrado. Uma guilda marcada como indisponível por um operador retorna 403 MISSING_ACCESS antes da rota ser executada.

Listar banimentos da guilda é a única operação que lê um registro de banimento, e não há operação de banimento em massa.

Objeto guild ban

Um objeto de banimento de guilda nomeia a conta banida, o moderador, o motivo e qualquer expiração. Criar um banimento para um usuário que já está banido substitui o registro existente.

Estrutura

Campo	Tipo	Descrição
user	objeto partial user	A conta banida
reason¹	?string	O motivo do banimento armazenado, ou null quando nenhum for registrado
moderator_id	snowflake	A conta que emitiu ou substituiu mais recentemente o banimento
banned_at²	ISO8601 timestamp	Momento em que o banimento foi emitido ou substituído mais recentemente
expires_at³	?ISO8601 timestamp	Momento em que um banimento temporário deixa de se aplicar, ou null para um banimento permanente

¹ O reason do corpo quando esse campo for fornecido, e o valor X-Audit-Log-Reason quando for omitido ou null

² Substituir um banimento reescreve esse valor, portanto, ele registra a emissão mais recente

³ Um banimento temporário expirado é removido e nunca retornado com um expires_at passado

Exemplo

{
  "user": {"id": "1489002177550843906", "username": "spammer", "discriminator": "0042"},
  "reason": "Advertising",
  "moderator_id": "1489002177550843905",
  "banned_at": "2026-08-14T09:12:44.000Z",
  "expires_at": null
}

Um convite rejeitado por correspondência de IP retorna 403 USER_IP_BANNED_FROM_GUILD. Uma correspondência de conta ou e-mail retorna 403 USER_BANNED_FROM_GUILD. O Decoding Chat pula a verificação de IP quando o endereço da conta que está ingressando está na lista de isenção de banimento de IP do operador, ou quando a busca de IP classifica esse endereço como NAT em nível de provedor (carrier-grade NAT) ou acesso compartilhado. Adicionar um membro através da Admin API, instalar um bot por meio de OAuth2 e o ingresso automático na guilda “visionaries” após uma compra via Stripe ignoram todas as verificações de banimento. O ingresso automático na comunidade única verifica as correspondências de conta e IP e ignora a correspondência de e-mail.

Remover banimento da guilda libera o bloqueio de endereço IP e o bloqueio de e-mail. A exclusão permanente da conta banida exclui todos os banimentos de guilda que ela possui, o que libera ambos os bloqueios em todas as guildas de uma vez.

Listar banimentos da guilda

GET/v1/guilds/{guild_id}/bans

Bot

Retorna todo objeto guild ban da guilda. Requer BAN_MEMBERS.

Um não-membro não pode ter BAN_MEMBERS, portanto, um solicitante fora da guilda recebe 403 MISSING_PERMISSIONS.

A operação retorna a coleção completa em uma única resposta e não tem limite ou parâmetros de cursor. A resposta exclui banimentos temporários expirados e omite um banimento cuja conta não possa mais ser resolvida, portanto, o array pode ser menor do que o número de banimentos armazenados.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda

Resposta

Status	Corpo	Condição
200	array[objeto guild ban]	Os banimentos foram retornados
400¹	error response	O solicitante possui `BAN_MEMBERS` sem um autenticador cadastrado em uma guilda com MFA elevado
403²	error response	A guilda está indisponível, ou `BAN_MEMBERS` está ausente
404	error response	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`

¹ O código de erro é TWO_FACTOR_REQUIRED, retornado apenas depois que a própria permissão foi confirmada

² O código de erro é MISSING_ACCESS para uma guilda indisponível e MISSING_PERMISSIONS caso contrário

Limite de taxa

40 requisições a cada 10 segundos para cada usuário autenticado e ID de guilda, no bucket compartilhado guild:members::guild_id.

Criar ou substituir banimento da guilda

PUT/v1/guilds/{guild_id}/bans/{user_id}

Bot Audit reason

Cria um banimento de guilda ou substitui um existente, e retorna 204 com um corpo vazio. Requer BAN_MEMBERS. Emite um evento de Gateway Guild Ban Add.

Limitações

O solicitante não pode banir a si mesmo, e o Decoding Chat relata um auto-alvo como 404 UNKNOWN_MEMBER.
Banir um alvo que é membro também requer autoridade na hierarquia de funções (role hierarchy) sobre esse membro. O proprietário da guilda detém essa autoridade sobre todos, e nenhum outro solicitante a detém sobre o proprietário.
Um alvo que não é membro ainda pode ser banido, e o Decoding Chat recusa uma entrada posterior por essa conta.

Um reason (motivo) bloqueado retorna 403 CONTENT_BLOCKED.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda
user_id	snowflake	O ID da conta a ser banida

Corpo JSON

O corpo é opcional, assim como todo campo dentro dele. O Decoding Chat lê um corpo omitido ou apenas com espaços em branco como um objeto vazio, portanto, uma requisição sem corpo cria um banimento permanente que não exclui mensagens e não registra um motivo no corpo. Um corpo que não seja um JSON válido retorna 400 INVALID_FORM_BODY com o código de validação INVALID_FORMAT no caminho body.

Campo	Tipo	Descrição
delete_message_seconds?¹	integer	Idade das mensagens recentes do alvo na guilda a serem excluídas, em segundos (0-604800)
delete_message_days?²	integer	Idade legada dessas mensagens, em dias inteiros (0-7, padrão 0)
reason?³	?string	Motivo armazenado no registro do banimento (máx. 512 caracteres)
ban_duration_seconds?⁴	integer	Duração do banimento em segundos, seja 0 ou 60 até 63072000

¹ Zero e um campo omitido não excluem nada. O campo tem precedência sobre delete_message_days sempre que estiver presente, inclusive quando for 0

² Multiplicado por 86400 para produzir o intervalo efetivo, e apenas quando delete_message_seconds estiver ausente

³ Despojado de pontos de código de formato e controle removidos e cortado antes de seu tamanho ser medido. Um resultado mais longo falha com STRING_LENGTH_INVALID no caminho reason

⁴ Zero e um campo omitido criam um banimento permanente. Qualquer valor fora de 60 até 63072000, que equivale a dois anos, falha com INVALID_FORMAT

Uma entrada de MEMBER_BAN_ADD registra options.delete_message_seconds quando o intervalo efetivo é positivo, qualquer que seja o campo que o definiu. Um banimento que não exclui nada não registra nenhuma opção, e a opção depreciada delete_member_days está presente apenas em uma entrada escrita antes deste campo.

Um reason omitido ou null recai para o valor X-Audit-Log-Reason, enquanto um valor fornecido que normaliza para a string vazia é armazenado como null sem substituição. O motivo da entrada de auditoria é o cabeçalho quando a solicitação envia um, e o motivo do banimento armazenado caso contrário.

Resposta

Status	Corpo	Condição
204	vazio	O banimento foi criado ou substituído
400¹	error response	A duração, o intervalo de exclusão ou o motivo é inválido, ou o solicitante possui `BAN_MEMBERS` sem um autenticador cadastrado em uma guilda com MFA elevado
403²	error response	A guilda está indisponível, conteúdo bloqueado foi fornecido, `BAN_MEMBERS` está ausente, ou a autoridade de hierarquia sobre o membro alvo está ausente
404	error response	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`
404³	error response	A conta alvo não existe, ou o alvo é o próprio solicitante

¹ O código de erro de autenticador ausente é TWO_FACTOR_REQUIRED, retornado apenas depois que a própria permissão foi confirmada

² O código de erro é MISSING_ACCESS para uma guilda indisponível, CONTENT_BLOCKED para uma string bloqueada e MISSING_PERMISSIONS caso contrário

³ O código de erro é UNKNOWN_USER para uma conta que não existe e UNKNOWN_MEMBER para um solicitante que nomeia a si mesmo, e a verificação de auto-alvo é executada primeiro

Efeitos colaterais

A operação registra uma entrada de auditoria MEMBER_BAN_ADD com os campos de alteração de banimento de guilda. Ela emite Guild Audit Log Entry Create e Guild Ban Add, sujeito à filtragem de eventos. Um intervalo de exclusão positivo exclui permanentemente as mensagens de guilda do alvo dentro desse intervalo.

Um membro atual é removido. A guilda recebe Guild Member Remove e a conta banida recebe Guild Delete. Nenhuma entrada de auditoria MEMBER_KICK é registrada.

Um banimento não preserva um tempo limite de comunicação ativo (timeout) para uma reentrada posterior, enquanto Remover membro da guilda sim. A conta banida perde o apelido na guilda, o hash do avatar da guilda, o hash do banner da guilda, a biografia, os pronomes, a cor de destaque e o conjunto de funções. Seus estados de leitura e configurações da guilda permanecem intactos.

A partir desse ponto, o Decoding Chat recusa uma tentativa de entrada pela conta banida. As correspondências de endereço e e-mail descritas em objeto guild ban também se aplicam.

Limite de taxa

20 requisições a cada 10 segundos para cada usuário autenticado e ID de guilda, no bucket guild:member:remove::guild_id.

Remover banimento da guilda

DELETE/v1/guilds/{guild_id}/bans/{user_id}

Bot Audit reason

Remove um banimento de guilda existente e retorna 204 com um corpo vazio. Requer BAN_MEMBERS. Emite um evento de Gateway Guild Ban Remove.

O Decoding Chat rejeita um alvo que não está banido com 400 INVALID_FORM_BODY.

Parâmetros de rota

Campo	Tipo	Descrição
guild_id	snowflake	O ID da guilda
user_id	snowflake	O ID da conta banida

Resposta

Status	Corpo	Condição
204	vazio	O banimento foi removido
400¹	error response	O alvo não está banido, ou o solicitante possui `BAN_MEMBERS` sem um autenticador cadastrado em uma guilda com MFA elevado
403²	error response	A guilda está indisponível, ou `BAN_MEMBERS` está ausente
404	error response	A guilda não existe e a requisição retorna `UNKNOWN_GUILD`

¹ Um alvo que não está banido retorna INVALID_FORM_BODY com USER_IS_NOT_BANNED para user_id. O código de autenticador ausente é TWO_FACTOR_REQUIRED, retornado apenas após a confirmação da permissão

² O código de erro é MISSING_ACCESS para uma guilda indisponível e MISSING_PERMISSIONS caso contrário

Efeitos colaterais

A operação exclui o banimento junto com os bloqueios de endereço e e-mail que ele possuía. Ela registra uma entrada de auditoria MEMBER_BAN_REMOVE cuja lista de alterações contém os campos de alteração de banimento da guilda removidos, emite Guild Audit Log Entry Create e emite Guild Ban Remove para as sessões da guilda, sujeito à filtragem de eventos.

Ela não restaura a associação removida, os campos do perfil da guilda e as funções que essa associação possuía, ou as mensagens excluídas. A conta desbanida pode entrar novamente através de um convite comum.

Um banimento de IP em toda a instância é um mecanismo separado no qual esta operação não toca. Toda requisição de um endereço que ele cobre ainda é recusada com 403 GLOBAL_IP_BANNED para um banimento permanente e 403 GLOBAL_IP_TEMPORARILY_BANNED para um de 24 horas.

Limite de taxa

20 requisições a cada 10 segundos para cada usuário autenticado e ID de guilda, no bucket guild:member:remove::guild_id.