Skip to main content

Heartbeats (ping/pong)

BlockDB sends periodic WebSocket ping frames. Clients must respond with pong to keep the connection alive.
Most WebSocket libraries handle ping/pong automatically. If yours does not, enable keepalives or implement pong responses.

Idle timeout

Connections with no active subscriptions (or missing heartbeat responses) may be terminated after an idle period.
  • Recommendation: subscribe soon after connecting and keep ping/pong enabled.
  • If you intentionally idle: close the socket gracefully and reconnect when needed.

Reconnection strategy

You should assume transient disconnects (network, deploys, backpressure). Use exponential backoff with jitter:
  • 1s โ†’ 2s โ†’ 4s โ†’ 8s โ€ฆ (cap at ~30s)
  • add random jitter (e.g., ยฑ20%)

Resubscribe after reconnect

The WebSocket connection state is not preserved across reconnects. Maintain a local list of active subscriptions and re-send subscribe messages after open. For data continuity and reconciliation (especially around reorgs), see: Reliability & Reorgs.

Backpressure & rate control

If the server cannot deliver messages fast enough (or your client cannot process them fast enough), the connection may be closed to protect the system.
  • Common signal: close code 1013 TRY_AGAIN_LATER
  • What to do:
    • reconnect with longer backoff (and jitter)
    • reduce subscription count
    • add or tighten filters (params) on high-volume streams
    • move heavy processing off the receive loop
See: WSS Error Codes

Logging & support

When debugging connection stability, always log:
  • close code + reason (if provided)
  • timestamp (UTC)
  • the last subscribe message(s) you sent (redact API key)

See also

Last modified on January 17, 2026