Connection lifecycle - ParlayX API

A connection runs from the welcome frame the server sends on connect to the goodbye it sends just before closing. This page covers everything that happens at the connection level — independent of any individual subscription.

`welcome`

Immediately after the upgrade succeeds, the server sends a welcome frame:

{
  "type": "welcome",
  "v": 1,
  "serverTimestamp": 1748020034123,
  "customerId": "9a4b7e2c-1a64-4dca-9d6e-1b8c2d3f4a5b",
  "connectionId": "1d3a9c44-cf21-4f33-9211-2b9b1adf67e8",
  "activeConnections": 1,
  "limits": { "maxSubscriptionsPerConnection": 200, "maxConnections": 20, "connectionTtlSeconds": 28800 }
}

Field	Meaning
`customerId`	Your account identifier.
`connectionId`	This connection’s identifier. Quote it in any support request so we can find your session in our logs.
`activeConnections`	How many connections your account currently holds, including this one.
`limits`	The caps that apply to this connection — see below.

Treat welcome as the signal that the connection is ready: wait for it before sending your first subscribe.

Connection limits

The welcome.limits object reports the caps for your connection:

Field	Meaning
`maxSubscriptionsPerConnection`	Maximum active `(market, channel)` subscriptions on this connection (currently 200). Exceeding it yields a `QUOTA_EXCEEDED` error.
`maxConnections`	Maximum simultaneous connections for your account across the whole service (currently 20). A connect attempt past it is rejected with HTTP `429` at the WebSocket handshake.
`connectionTtlSeconds`	The connection’s maximum lifetime — see Connection lifetime.

Scaling past the subscription cap is by design: open multiple connections. Spread your markets across connections; one stream key authenticates all of them, up to your maxConnections. The defaults give one account up to 20 × 200 = 4,000 simultaneous (market, channel) subscriptions — if you need more, reach out and we can raise your account’s connection limit. Dropped or unresponsive connections are cleaned up automatically within about a minute and stop counting against maxConnections.

Keepalive

The server sends WebSocket-protocol pings every 30 seconds; any standard WebSocket client answers them automatically. A connection that stops answering is treated as idle and closed with idleTimeout. You can also send an application-level ping and get a pong back — useful as an explicit liveness check or to keep an otherwise-quiet connection active:

{ "type": "ping", "requestId": "…" }

{ "type": "pong", "v": 1, "serverTimestamp": 1748020034300, "requestId": "…" }

The requestId you send is echoed on the pong. This is independent of the WebSocket-protocol pings above.

Connection lifetime and `goodbye`

Just before the server closes a connection, it sends a goodbye frame with a reason, then closes the socket. Always reconnect on a goodbye or any unexpected close.

{ "type": "goodbye", "v": 1, "serverTimestamp": 1748020034400, "reason": "ttl" }

`reason`	Meaning	What to do
`ttl`	The connection reached `connectionTtlSeconds`.	Reconnect. Schedule this proactively before the TTL to avoid a visible gap.
`shutdown`	The serving task is shutting down (deploy or scale-in).	Reconnect; you land on another task. Data keeps flowing briefly after the warning, so you have time to reconnect cleanly.
`noActiveSubs`	The connection sat with zero subscriptions past a grace period.	Reconnect when you next need data; keep at least one subscription otherwise.
`idleTimeout`	The connection was idle / unresponsive to pings.	Reconnect; make sure your client answers WebSocket pings.
`authRevoked`	The stream key was revoked.	Stop reconnecting with that key; obtain a new one.
`kicked`	The connection was closed by the server (e.g. a persistently slow reader that fell too far behind).	Reconnect; ensure you’re draining the socket fast enough.

Reconnect guidance

Reconnect with backoff on any close, but reconnect immediately (after a short jitter) on ttl and shutdown — those are routine.
A 503 during the upgrade means the gateway is at capacity. Back off briefly and retry; you’ll be routed to fresh capacity.
A 429 during the upgrade means your account is at its maxConnections limit. Retrying does not help — close a connection you no longer need (or wait ~90 seconds after an ungraceful drop for its slot to free), and contact us if you need the limit raised.
On reconnect, re-subscribe to your markets. Each book subscription replays a fresh snapshot, so your state rebuilds automatically. There is no resume-from-offset to manage.
Don’t reconnect on authRevoked; the key is dead.

​welcome

​Connection limits

​Keepalive

​Connection lifetime and goodbye

​Reconnect guidance

`welcome`

Connection limits

Keepalive

Connection lifetime and `goodbye`

Reconnect guidance