Opcodes e códigos de fechamento

Um opcode é o número identificador de um payload do Gateway. Um código de fechamento (close code) é o número que o Gateway envia ao encerrar uma conexão WebSocket. Todos os valores nesta página pertencem exclusivamente ao Gateway principal. Consulte Visão geral do Gateway para a máquina de estados da conexão e Comandos do cliente para os formatos de payload.

Opcodes

Op	Nome	Direção
0	Dispatch	Servidor para cliente
1	Heartbeat	Bidirecional
2	Identify	Cliente para servidor
3	Presence Update	Cliente para servidor
4	Voice State Update	Cliente para servidor
5	Voice Server Ping	Reservado
6	Resume	Cliente para servidor
7	Reconnect	Servidor para cliente
8	Request Guild Members	Cliente para servidor
9	Invalid Session1	Servidor para cliente
10	Hello	Servidor para cliente
11	Heartbeat ACK	Servidor para cliente
12	Gateway Error	Reservado
14	Lazy Request	Cliente para servidor
15	Request Guild Counts	Cliente para servidor
16	Request Channel Member Counts	Cliente para servidor

¹ O Decoding Chat nunca envia o Opcode 9 com d: true, de modo que um Invalid Session nunca é uma instrução para retomar

Payload e momento de envio

Op	Payload	Quando é enviado
0	Dados específicos do evento	O servidor envia um evento com nome em t e sequência em s1
1	Última sequência processada ou null pelo cliente; null pelo servidor	O cliente envia periodicamente. O servidor solicita heartbeat imediato caso 90% do intervalo decorra sem confirmação2
2	Objeto de Identify	O cliente inicia uma sessão autenticada
3	Objeto de Presence Update	O cliente atualiza sua presença na sessão
4	Objeto de Voice State Update	O cliente conecta, move, altera ou desconecta da voz
5	Não implementado	Nunca enviado. Clientes que o enviarem serão desconectados3
6	Objeto de Resume	O cliente restaura uma sessão retida4
7	Sem campo d	O Gateway solicita reconexão e fecha o socket com 40005
8	Objeto de Request Guild Members	O cliente solicita páginas de membros de servidores
9	Booleano literal false	A sessão indicada não pôde ser alcançada, seq abaixo do piso de replay ou sessão ativa encerrada6
10	Objeto com heartbeat_interval	Enviado assim que o WebSocket é aceito, antes de ler payloads do cliente
11	Sem campo d	Confirma o recebimento de um heartbeat válido
12	Não implementado	Nunca enviado. Erros chegam como Dispatch ou no frame de fechamento
14	Objeto de Lazy Request	O cliente atualiza assinaturas de servidores
15	Objeto de Request Guild Counts	O cliente consulta contagens de membros de servidores
16	Objeto de Request Channel Member Counts	O cliente consulta contagens de membros de canais

¹ Resumed contém a sequência atual sem incrementá-la; Dispatches reproduzidos mantêm a sequência original de criação

² Responda a uma solicitação de heartbeat do servidor imediatamente, mantendo o envio regular agendado

³ Enviar Opcode 5 ou 12 resulta no mesmo fechamento que um opcode indefinido

⁴ Resume é aceito havendo ou não sessão vinculada no momento

⁵ O Opcode 7 precede o fechamento quando o nó estiver em drain, em migração de sessão ou quando um novo socket assumir a sessão

⁶ Após esse frame, o socket fica não autenticado. Em falha de Resume em socket já vinculado, a sessão vinculada permanece

O registro é completo. O Opcode 13 e valores acima de 16 são indefinidos.

Ordem de resolução de payloads de entrada pelo Gateway:

1. Payload sem d não alcança o comando. Identify fecha com 4005. Todos os demais fecham com 4001.
2. Heartbeat e Resume são processados independentemente de haver sessão vinculada.
3. Identify fecha com 4005 caso uma sessão já esteja vinculada.
4. Qualquer outro opcode fecha com 4003 enquanto a conexão não estiver autenticada.
5. Com sessão vinculada, Presence Update, Voice State Update, Request Guild Members, Lazy Request, Request Guild Counts e Request Channel Member Counts são processados. Qualquer outro valor fecha com 4001.

Opcodes desconhecidos do servidor mantêm compatibilidade futura

Clientes DEVEM ignorar frames com opcodes desconhecidos recebidos do servidor e NÃO DEVEM fechar ou reconectar a conexão por esse motivo.

Códigos de fechamento

Código	Nome	Significado
4000	Unknown error	Drain do nó, erro não classificado de sessão ou sessão retida inalcançável
4001	Unknown opcode	Opcode indefinido, opcode exclusivo de servidor ou payload sem d
4002	Decode error	Tamanho de payload, fluxo de compressão, codificação ou campos inválidos
4003	Not authenticated	Comando autenticado recebido antes de Identify ou Resume
4004	Authentication failed	Token inválido ou não proprietário da sessão retida
4005	Already authenticated	Identify recebido enquanto uma sessão já estava vinculada, ou sem d
4007	Invalid sequence	Sequência de Heartbeat ou Resume fora dos limites aceitos
4008	Rate limited	Limite de conexões simultâneas, payloads por conexão, por IP ou por usuário excedido
4009	Session timeout	Mais de 45.000 ms decorridos sem confirmação de heartbeat enquanto o Gateway a aguardava
4010	Invalid shard	O valor shard do Identify não é um par [shard_id, shard_count] válido
4011	Sharding required	Mais de 2.500 servidores vinculados a uma única sessão de bot
4012	Invalid API version	O parâmetro de conexão v está ausente ou não é 1

O código 4006 não é atribuído, e nenhum código acima de 4012 é definido.

Resultado na sessão

Código	Retomável	Estado resultante
4000	Condicional	Fechado. A sessão vinculada permanece recuperável1
4001	Condicional	Fechado. Sessão previamente estabelecida permanece retida
4002	Condicional	Fechado. Sessão previamente estabelecida permanece retida
4003	Não	Fechado. Nenhuma sessão existe nesta conexão
4004	Condicional	Fechado. Resume não invalida a sessão que nomeou2
4005	Condicional	Fechado. Sessão previamente estabelecida permanece retida
4007	Não para esta tentativa	Fechado. A sessão retida aguarda até sua janela expirar
4008	Condicional	Fechado. Sessão previamente estabelecida permanece retida
4009	Condicional	Fechado. Sessão previamente estabelecida permanece retida
4010	Não	Fechado. Nenhuma sessão foi criada
4011	Não	Fechado. Nenhuma sessão foi criada
4012	Não	Fechado antes do Hello. Nenhuma sessão existe

¹ Um fechamento que deixe a sessão sem socket inicia uma nova janela de retenção de 60.000 ms a partir da desconexão

² Um Resume com token inválido preserva a sessão até o término de sua janela de retenção, permitindo que o token correto a recupere

Reconectar sem alterações reproduz 4004, 4010 e 4012

Altere o token, o par de shards ou o parâmetro de versão antes de tentar uma nova conexão.

Motivos de fechamento

O Gateway envia uma string de motivo exata em cada fechamento de aplicação.

Motivo	Código	Causa
Invalid API version	4012	O parâmetro de conexão v está ausente ou não é 1
Too many connections	4008	O IP de origem atingiu 256 conexões Gateway simultâneas
Encode failed	4002	Falha na codificação do frame Hello
Compression failed: zstd-stream	4002	Falha na compressão zstd do frame Hello
Payload too large	4002	Mensagem de entrada excedeu 4.096 bytes na rede ou após descompressão
Decompression failed	4002	Mensagem comprimida de entrada não pôde ser descomprimida
Decode failed	4002	Payload não é JSON válido ou decodificou em algo que não é objeto
Invalid payload	4002	Objeto decodificado não possui campo op
Rate limited	4008	Orçamento de payloads da conexão, do IP ou da conta foi excedido
Unknown opcode	4001	Opcode indefinido, exclusivo de servidor ou payload sem campo d
Not authenticated	4003	Comando autenticado recebido antes da vinculação de sessão
Already authenticated	4005	Identify recebido com sessão já vinculada ou sem campo d
Invalid identify payload	4002	Identify sem token/properties ou com tipos inválidos
Invalid shard	4010	Valor shard do Identify não é um par [shard_id, shard_count] válido
Sharding required	4011	Mais de 2.500 servidores associados ao shard do bot
Too many sessions	4008	Usuário atingiu o teto de 100 sessões ativas simultâneas
Invalid token	4004	Token do Identify inválido ou token do Resume não é dono da sessão
Failed to start session	4000	Falha não classificada na criação da sessão
Invalid resume payload	4002	Resume inválido, token/session_id ausentes ou seq não inteiro
Invalid sequence	4007	Sequência de Heartbeat ou Resume fora dos limites válidos
Invalid presence payload	4002	Presence Update inválido ou com valor desconhecido de status
Session unavailable	4000	Sessão retida inalcançável durante o Resume
Session drain requested; reconnect to continue	4000	Opcode 7 enviado imediatamente antes do fechamento
Heartbeat timeout	4009	Nenhuma confirmação de heartbeat recebida dentro de 45.000 ms

Fechamentos normais de WebSocket

A conexão pode ser encerrada sem código de aplicação do Decoding Chat (ex.: quedas de rede, resets de proxy, códigos 1000 ou 1001). Nesses casos, a sessão permanece retida e disponível para recuperação por 60.000 ms.