Connection
How to recover from a dropped WebSocket. Backoff, token re-mint, and what arrives first when the new connection opens.
When a WebSocket drops, the recovery flow is short: mint a fresh token, open a new WebSocket, wait for resumed. You do not replay missed events; once back online you are live again.
Recommended client logic
- Detect close (close code, or heartbeat timeout; see Heartbeat)
- Wait a backoff interval
- Mint a fresh token at
/v1/token - Open a new WebSocket at
/v1?token=... - Wait for the first
resumedevent - Resume normal event handling
Backoff
Start at 1 second and double on each consecutive failure, capping around 30 seconds. Reset to 1 second once any reconnection succeeds.
| Attempt | Wait before attempt |
|---|---|
| 1 | 1 s |
| 2 | 2 s |
| 3 | 4 s |
| 4 | 8 s |
| 5 | 16 s |
| 6+ | 30 s (cap) |
Add ~25% jitter to avoid thundering-herd reconnects across all your customer instances.
Token re-mint
You must mint a fresh token for each new WebSocket. Tokens are valid for 10 minutes after mint and are bound to the WebSocket upgrade only; an open connection survives token expiry, but a new connection always needs a new token.
If the mint endpoint returns 429, wait the seconds in the Retry-After header before retrying. See Authentication for the full mint flow.
What you receive first
After a successful reconnect, the first message is always resumed:
{ "type": "resumed", "maxSubs": 5000 }After that, live events stream as they happen. Events your account would have received during the disconnected gap are not replayed.
When you keep getting close 1008
A 1008 close with reason customer_unknown means your account configuration changed while you were offline. Mint a fresh token and reconnect once; if you get the same close again immediately, contact us.
See Close codes for the full close-code reference.