discord.js Client and Discord Gateway: session resumption behavior during zero-downtime deployments

Resolution

A new discord.js process cannot natively resume a Gateway session from a previous process because the required session_id and sequence number are stored in-memory. To achieve zero-downtime event delivery, you must either implement an external state handoff (complex and unsupported by the high-level API) or migrate to an Interactions Endpoint URL for slash commands, which removes the Gateway dependency for those specific events.

Session Resumption Constraints

While the Discord Gateway allows a RESUME payload to recover a session, discord.js manages this state internally. For a new process to resume a session, it would need the exact session_id and the last received sequence number. Because the library does not provide a public API to manually inject these values into a new Client instance upon startup, a process restart effectively forces a new IDENTIFY call.

Gateway Limits and Deployment Risks

Rolling restarts are constrained by two primary factors:

• The Resume Window: Discord maintains session state for a limited time (typically a few minutes). If the new process does not resume within this window, a fresh IDENTIFY is required.
• Identify Rate Limits: Discord enforces a strict limit on how many times a bot can identify per 24-hour window. Rapid deployment cycles or crash-loops can trigger this limit, resulting in a complete lockout from the Gateway.

HTTP Interactions as an Alternative

Moving to an Interactions Endpoint URL (Webhooks) eliminates the Gateway session dependency for slash commands, context menus, and component interactions. Instead of a persistent WebSocket, Discord sends a POST request to your server. This allows for true zero-downtime deployments via a load balancer or rolling update, as the HTTP endpoint remains reachable regardless of the internal process state.

Implementation Steps for HTTP Interactions

1. Configure the Interactions Endpoint URL in the Discord Developer Portal.
2. Implement a web server (e.g., Express or Fastify) to handle the POST requests.
3. Implement the mandatory cryptographic verification of the request signature using your Public Key to prevent spoofing.
4. Respond with the appropriate interaction response type (e.g., PONG for the initial verification or a JSON response for the command).

Note: HTTP endpoints only support Interaction events. If your bot relies on MESSAGE_CREATE or other Gateway-only events, you will still experience a delivery gap during process replacement.

Diagnostic Requirement

To determine if the Identify rate limit is your primary bottleneck, please provide the specific HTTP status codes or Gateway close codes (e.g., 4014) observed in your logs during deployment failures.