Reconnection & lifecycle

The client keeps the connection healthy and recovers from drops on its own. In the normal case you never write reconnect logic. You subscribe once, and your subscriptions survive across disconnects. This page covers what happens underneath so you know when to intervene.

Keepalive

The client runs an application-level ping/pong on the open socket. If pongs stop coming back it treats the connection as dead and tears it down, which kicks off a reconnect. A single dropped pong is tolerated, so a brief network blip doesn’t cause a needless reconnect. This is layered on top of the server’s own connection-level keepalive. See Connection lifecycle.

Reconnect with resubscribe

When the socket closes unexpectedly, the client reconnects with exponential backoff and jitter, reporting a reconnect before each attempt:

stream = StreamClient(
    on_reconnecting=lambda event: print(
        f"reconnecting (attempt {event.attempt}) in {event.delay_seconds}s"
    ),
)

stream.on("RECONNECTING", ({ attempt, delayMs }) =>
  console.warn(`reconnecting (attempt ${attempt}) in ${delayMs}ms`),
);

Server-assigned subscriptionIds are scoped to a single connection and don’t survive a reconnect, so the client replays your active subscriptions (the (market, channel) pairs you asked for) on every new connection. You’ll receive a fresh SUBSCRIBED ack and a new SNAPSHOT for each. Because resubscribe is automatic, subscriptions you create before the socket is even open are honored too (they’re sent once the connection is ready). The backoff budget resets only once a connection is confirmed by a WELCOME frame, so a transient drop after a healthy session gets the full retry budget, while an endpoint that never establishes a session is bounded (see below). Subscriptions the server permanently retires are not replayed: a STATUS frame with state: "CLOSED" or "UNSUPPORTED", or an ERROR frame rejecting a market at subscription time, prunes that entry so it isn’t retried on reconnect.

`GOODBYE` and terminal disconnects

Before closing a connection the server sends a GOODBYE frame with a reason. The client treats these two ways:

Recoverable: SHUTDOWN, TTL, IDLE_TIMEOUT, and NO_ACTIVE_SUBS (when you still have subscriptions to replay). The client reconnects normally.
Terminal: AUTH_REVOKED and KICKED (and NO_ACTIVE_SUBS when there’s nothing left to resubscribe). Reconnecting with the same key would be futile, so the client stops.

The termination reason is goodbye: followed by the reason exactly as the server sent it, for example goodbye:AUTH_REVOKED. Compare against that casing. When the client stops for good it reports a termination: a terminated event in TypeScript, the on_terminated callback in Python. This also happens if reconnecting repeatedly fails without ever establishing a session (a revoked key or an unreachable endpoint), instead of looping forever. Termination is final: that client will not reconnect. A fresh client starts with none of your handlers or subscriptions, so wrap setup in a function that creates the client, registers handlers, and subscribes, then call it both initially and on resume. In Python the iteration also ends, and a terminal failure is raised out of the async for, so the restart loop is an ordinary while rather than a callback that re-enters itself.

import asyncio

from parlayx.stream import StreamClient

MAX_RESTARTS = 5
RESTART_DELAY_SECONDS = 30
TERMINAL_REASONS = {"goodbye:AUTH_REVOKED", "goodbye:KICKED"}


async def run_forever(token_id: str) -> None:
    restarts = 0

    while True:
        reason: str | None = None
        # A confirmed session means the credential and endpoint are good, so the
        # budget below is about consecutive failures, not lifetime ones.
        confirmed = False

        def remember(event) -> None:
            nonlocal reason
            reason = event.reason

        try:
            async with StreamClient(on_terminated=remember) as stream:
                await stream.subscribe([{"venue": "POLYMARKET", "tokenId": token_id}])
                async for frame in stream:
                    if frame.type == "WELCOME":
                        confirmed = True
                        restarts = 0
                    elif frame.type == "SNAPSHOT":
                        ...  # apply the snapshot to your local book
        except Exception as error:
            print("stream failed:", error)

        # A revoked or kicked key refuses every retry, so never restart on these.
        if reason in TERMINAL_REASONS:
            print("stream terminated:", reason)
            return

        # Everything else is worth one more try, but bound it. A revoked or
        # unknown key fails the upgrade with no goodbye frame, so it arrives here
        # indistinguishable from a real outage. Without a cap, each restart buys
        # a fresh reconnect budget and the loop never ends.
        if not confirmed and restarts >= MAX_RESTARTS:
            print("giving up; check the signing key, the clock, and the endpoint")
            return

        restarts += 1
        await asyncio.sleep(RESTART_DELAY_SECONDS)

const MAX_RESTARTS = 5;
const RESTART_DELAY_MS = 30_000;
let restarts = 0;

function start() {
  const stream = createStreamClient({
    keyId: process.env.PARLAYX_KEY_ID!,
    privateKeyHex: process.env.PARLAYX_PRIVATE_KEY_HEX!,
  });

  /* A confirmed session means the credential and endpoint are good, so the
     budget below is about consecutive failures, not lifetime ones. */
  stream.on("WELCOME", () => {
    restarts = 0;
  });

  stream.on("SNAPSHOT", (frame) => {
    /* apply the snapshot to your local book */
  });

  stream.on("TERMINATED", ({ reason }) => {
    console.error(`stream terminated: ${reason}`);

    /* A revoked or kicked key refuses every retry, so never restart on these. */
    if (reason === "goodbye:AUTH_REVOKED" || reason === "goodbye:KICKED") return;

    /* Everything else is worth one more try, but bound it. A revoked or unknown
       key 401s at the upgrade with no goodbye frame, so it arrives here as
       `maxReconnectAttempts`, indistinguishable from a real outage. Without a
       cap, each restart buys a fresh reconnect budget and the loop never ends. */
    if (restarts >= MAX_RESTARTS) {
      console.error("giving up; check the signing key, the clock, and the endpoint");
      return;
    }
    restarts += 1;
    setTimeout(start, RESTART_DELAY_MS);
  });

  stream.subscribe([{ venue: "POLYMARKET", tokenId: "71045620195867637" }]);
  return stream;
}

const stream = start();

A drifted host clock is worth ruling out before the key: the handshake signature covers a timestamp the server checks against its own, so a clock more than 30 seconds off makes every upgrade fail the same way a bad key does.

Closing intentionally

Closing the client yourself is not a disconnect it recovers from. It closes the socket and stops all reconnect attempts. Use it on shutdown or when you’re done streaming.

await stream.close()

# Or let the context manager do it:
async with StreamClient() as stream:
    ...

stream.close();

Reference

Streaming

Reconnection & lifecycle

Keepalive

Reconnect with resubscribe

`GOODBYE` and terminal disconnects

Closing intentionally

​Keepalive

​Reconnect with resubscribe

​GOODBYE and terminal disconnects

​Closing intentionally

Keepalive

Reconnect with resubscribe

`GOODBYE` and terminal disconnects

Closing intentionally