WebSocket reconnection patterns

2026-11-19

Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs before acting on a number.

Reconnecting is easy. The failure that costs money is what happens afterwards: the stream resumes, updates arrive, everything looks normal, and your view of positions is silently wrong because of what arrived while you were gone.

Nothing reports this. That is what makes it the most common serious bug in stream-based trading clients.

Why a stream is not a source of truth

A WebSocket feed is a sequence of changes. Your state is the accumulation of those changes applied to a starting snapshot.

Miss one and your state diverges permanently. Not temporarily — there is no mechanism that brings it back, because subsequent updates are deltas applied to an already-wrong base. An order book with a missed update stays wrong until you rebuild it.

Compare an error: an error tells you something failed. Divergence tells you nothing at all, and you act on the wrong numbers with full confidence.

The pattern that works

connect
  → subscribe
  → REST snapshot            ← the step people skip
  → apply buffered updates
  → steady state
      ↓ disconnect
  → reconnect with backoff
  → resubscribe
  → REST snapshot again      ← and skip again

The REST reconciliation after every reconnect is the whole thing. Not after the first connect — after every reconnect, including brief ones that barely registered.

Order matters: subscribe before taking the snapshot, and buffer the updates that arrive while the snapshot is in flight. Taking the snapshot first and then subscribing leaves a gap exactly the width of your own latency.

Sequence numbers

Where the venue provides them, check for gaps. A missing sequence number is the only positive signal you will get that your state is stale.

CCXT models this explicitly: ChecksumError is a subclass of InvalidNonce under NetworkError — a stream consistency failure classified as a network problem rather than an exchange refusal. That is the right classification and a useful reminder that the correct response is to rebuild, not to retry the last message.

If a venue publishes a book checksum, verify it periodically. It is the cheapest divergence detector available, and it catches the case where nothing appeared to go wrong.

Backoff, and why it is not optional

Reconnect loops without backoff cause their own outage.

Exponential backoff with jitter. Without jitter, every client that disconnected together reconnects together.
Respect connection limits. Hyperliquid documents a maximum of 10 WebSocket connections and 30 new connections per minute per IP. A tight reconnect loop burns that allowance in seconds and then cannot connect at all.
Watch for session-level message limits. Bybit returns 20003, “Too frequent requests under the same session”; Hyperliquid caps messages at 2000 per minute and subscriptions at 1000.

A leaking reconnect loop is also the most common cause of Bybit’s 10003 on classic accounts — “too many sessions under the same UID” — because sessions accumulate faster than they are reaped. See Bybit API error 10003.

Detecting a dead connection

The worst disconnect is the one the socket does not notice: TCP still open, no data arriving.

Use the venue’s heartbeat or ping frame where one exists.

Add a data-staleness timer independently. If no message of any kind has arrived in longer than expected for the subscriptions you hold, treat the connection as dead and cycle it. A quiet market and a dead socket look identical from the application’s side, and the timer is what distinguishes them.

What must not come from the stream

Two things worth stating flatly.

Never confirm an order from the stream alone. The REST response to your own request is the more direct answer. An order update that did not arrive is not evidence the order does not exist — see retrying a failed order is not safe.

Never let a reconnect trigger trading decisions before reconciliation completes. The window between “stream is back” and “state is verified” is where positions get doubled, because the strategy sees a position it believes is missing.

Keeping REST budget in reserve

Reconciliation needs REST calls, and reconnects cluster with market stress — which is also when you are most likely to be near a rate limit from everything else going on.

So reserve REST headroom that routine polling cannot consume. Being unable to reconcile after a reconnect, because a data refresh loop used the budget, is the specific failure to design against. This is the same argument as in WebSocket vs REST for trading: keep the capacity to ask what actually happened.

FAQ

Do I need to resync after a WebSocket reconnect?

Yes, every time, via REST. A stream delivers changes rather than state, so any updates missed during the disconnect leave your view permanently wrong — and nothing reports it, because subsequent updates apply cleanly to a wrong base. Subscribe first, then snapshot, then apply the updates buffered in between.

How do I know if my order book is out of sync?

Sequence numbers and checksums, where the venue provides them. A gap in sequence numbers is the only positive signal of divergence you will get; without one, a stale book looks exactly like a current one. CCXT surfaces this as ChecksumError under NetworkError, and the correct response is to rebuild rather than retry.

Why does my WebSocket keep disconnecting?

Common causes are missing heartbeat responses, exceeding connection or subscription limits, and network paths that drop idle connections. Check the venue’s limits — Hyperliquid documents 10 connections and 30 new connections per minute per IP — and make sure your reconnect logic backs off, since a tight loop can exhaust the allowance and prevent reconnection entirely.

Can I confirm an order filled from the WebSocket feed?

Use it as a signal, not as confirmation. The REST response to your own order request is more direct, and the absence of a stream update is not evidence that nothing happened — it may simply be the update you missed. For anything consequential, reconcile against REST.