WebSocket Close Codes

​

Close Code Reference

​

Resumable Close Codes

​

4000: Unknown Error

1. Reconnect to the Gateway
2. Attempt to Resume with your session ID and last sequence
3. If Resume fails, send a new Identify

WebSocket Close Frame:
{
  "code": 4000,
  "reason": "Unknown error"
}

​

4001: Unknown Opcode

1. Fix your client to not send invalid opcodes
2. Reconnect and Resume

• Sending opcode 13 (skipped in spec)
• Sending opcodes > 14
• Typos in opcode field

​

4002: Decode Error

• Invalid JSON syntax
• Payload exceeds 4,096 bytes
• Missing required fields (op)
• Compression failure
• Encoding mismatch

1. Fix the payload format
2. Ensure payloads are under 4,096 bytes
3. Reconnect and Resume

WebSocket Close Frame:
{
  "code": 4002,
  "reason": "Payload too large"
}

​

4003: Not Authenticated

• Opcode 3: Presence Update
• Opcode 4: Voice State Update
• Opcode 8: Request Guild Members
• Opcode 14: Lazy Request

1. Reconnect
2. Send Identify or Resume
3. Wait for Ready/RESUMED
4. Then send other opcodes

WebSocket Close Frame:
{
  "code": 4003,
  "reason": "Not authenticated"
}

​

4005: Already Authenticated

• Sent Identify twice
• Sent Identify after Resume succeeded

1. Reconnect
2. Send only ONE Identify or Resume per connection

WebSocket Close Frame:
{
  "code": 4005,
  "reason": "Already authenticated"
}

​

4009: Session Timeout

1. Gateway sends Heartbeat (op 1) every ~13.75s
2. Client responds with Heartbeat ACK
3. Gateway waits up to 45s for ACK
4. If no ACK, closes with 4009

1. Ensure heartbeat timer is running
2. Respond to ALL heartbeat requests
3. Reconnect and Resume

// Pseudocode
setInterval(() => {
  if (Date.now() - lastHeartbeatAck > 45000) {
    // Connection is dead, reconnect
    reconnect();
  }
}, 5000);

​

Non-Resumable Close Codes

​

4004: Authentication Failed

• Token is malformed
• Token has expired
• Token was revoked
• Wrong token type (bot vs user)

1. Verify your token is correct
2. Obtain a new token if expired
3. Reconnect and send Identify with valid token
4. Do NOT attempt Resume

WebSocket Close Frame:
{
  "code": 4004,
  "reason": "Invalid token"
}

​

4007: Invalid Sequence

• Sequence is too old (session expired)
• Sequence is in the future (shouldn’t happen)
• Session data was lost server-side

1. Do NOT attempt Resume again
2. Reconnect and send a new Identify
3. Store sequence numbers more reliably

WebSocket Close Frame:
{
  "code": 4007,
  "reason": "Invalid sequence"
}

​

4008: Rate Limited

• General: 120 events per 60 seconds
• Request Guild Members: 3 per 10 seconds
• Voice State Update: 10 per second (queued beyond)

1. Wait at least 60 seconds before reconnecting
2. Review your code to reduce event frequency
3. Reconnect and send a new Identify
4. Do NOT attempt Resume

// Implement client-side rate limiting
const rateLimiter = {
  events: [],
  canSend() {
    const now = Date.now();
    this.events = this.events.filter(t => now - t < 60000);
    if (this.events.length >= 120) return false;
    this.events.push(now);
    return true;
  }
};

WebSocket Close Frame:
{
  "code": 4008,
  "reason": "Rate limited"
}

​

4012: Invalid API Version

wss://gateway.fluxer.example/?v=1&encoding=json

wss://gateway.fluxer.example/?encoding=json  # Missing v=1
wss://gateway.fluxer.example/?v=2            # Wrong version

1. Update your connection URL to include v=1
2. Reconnect
3. Send Identify

WebSocket Close Frame:
{
  "code": 4012,
  "reason": "Invalid API version"
}

​

4013: Acknowledgement Backpressure

• Event ACK buffer: 4,096 events
• Reaction buffer: 512 events
• Pending presence buffer: 2,048 events

• Client is blocking/hanging
• Network congestion
• Not acknowledging events

Acknowledgement backlog exceeded: kind=event_ack_buffer unacked=4096 current=4096 limit=4096 seq=5000 ack_seq=904

1. Fix your client to process events faster
2. Ensure event handlers are non-blocking
3. Reconnect and send Identify (cannot Resume)

// Process events asynchronously
gateway.on('dispatch', async (event) => {
  // Don't block the event loop
  setImmediate(() => handleEvent(event));
});

WebSocket Close Frame:
{
  "code": 4013,
  "reason": "Acknowledgement backlog exceeded: kind=event_ack_buffer unacked=4096 current=4096 limit=4096 seq=5000 ack_seq=904"
}

​

Reconnection Strategy

​

Implementation Example

class GatewayClient {
  handleClose(code, reason) {
    console.log(`Closed: ${code} - ${reason}`);
    
    const nonResumable = [4004, 4007, 4008, 4010, 4011, 4012, 4013];
    
    if (code === 4008) {
      // Rate limited
      setTimeout(() => this.connect(), 60000);
      this.sessionId = null; // Clear session
    } else if (nonResumable.includes(code)) {
      // Not resumable
      setTimeout(() => this.connect(), 1000 + Math.random() * 4000);
      this.sessionId = null;
    } else {
      // Resumable
      setTimeout(() => this.connect(), 1000);
      // Keep sessionId for Resume
    }
  }
  
  async connect() {
    this.ws = new WebSocket('wss://gateway.fluxer.example/?v=1&encoding=json');
    
    this.ws.on('open', () => {
      // Wait for Hello before sending Identify/Resume
    });
    
    this.ws.on('message', (data) => {
      const msg = JSON.parse(data);
      
      if (msg.op === 10) { // Hello
        if (this.sessionId) {
          this.resume();
        } else {
          this.identify();
        }
      }
    });
    
    this.ws.on('close', (code, reason) => {
      this.handleClose(code, reason.toString());
    });
  }
}

​

Monitoring

​

Summary