New Listings Feed · v2 WebSocket Connections and Reconnects

Wait for READY

After connection admission succeeds, the server sends one READY message before any events. Read the applied account settings from this message instead of hardcoding them.

A successful HTTP upgrade or WebSocket open callback does not guarantee admission. You can receive an application error followed by a close before READY, for example when a connection limit is reached.

READY message

Read the applied account settings from subscription. This example uses a PRO key:

{
  "type": "success",
  "code": "READY",
  "message": "Streaming started",
  "endpoint": "tokyo/full",
  "subscription": {
    "username": "example_user",
    "plan": "pro",
    "delay_ms": 0,
    "ip_limit": 1,
    "active_ips": 1,
    "expires_at": null
  }
}

Field	Notes
`endpoint`	Serving region and endpoint, such as `tokyo/full`, `tokyo/fast`, `ny/full`, or `ny/fast`.
`subscription.username`	Account username, or `null`.
`subscription.plan`	Applied plan: `feed_free`, `starter`, or `pro`.
`subscription.delay_ms`	Publish delay applied to this connection.
`subscription.ip_limit`	Maximum public IP addresses with simultaneous WebSocket connections for this key, per endpoint and region. See connection limits.
`subscription.active_ips`	Public IP addresses with active WebSocket connections for this key on this endpoint in this region, counted at admission and including yours. Two connections from the same IP count as one IP.
`subscription.expires_at`	Key expiry in ISO 8601 UTC, or `null`.

Receive only

Both v2 endpoints are receive-only. Do not send application messages on the socket. The server closes the connection with code 1008 if you do.

Ping and pong

Reply to WebSocket pings with a pong. Most WebSocket libraries handle this automatically. These are protocol control frames. Do not send a JSON heartbeat.

Reconnect

Retry transient failures with backoff, starting at 1 second and doubling up to 30 seconds. Add a little random jitter so clients do not reconnect together. When a failed upgrade includes Retry-After, wait at least that long, even if it exceeds your backoff cap. Reset backoff after READY, not merely after the socket opens.

Stop automatic retries for an invalid request, rejected or expired key, or unresolved connection limit. Correct the request, key, or connection usage before restarting. See the client examples for handling both HTTP upgrade failures and WebSocket closes.

Reconnecting resumes live events. Recover missed Full events through history.

Server close messages

When the server can send an application error before closing, the JSON message has type: "error" and a stable code.

Code	WebSocket close	What to do
`CONNECTION_LIMIT_REACHED`	`1008`	Close another connection or use an allowed IP.
`CONNECTION_CLOSED`	`1008`	Check for forbidden client messages or changed access before reconnecting.
`AUTHENTICATION_FAILED`	`1008`	Stop retries. Check that the key is active and allowed on the endpoint.
`KEY_EXPIRED`	`1008`	Renew the key before reconnecting.
`SERVER_UNAVAILABLE`	`1011`	Reconnect with backoff.

A server shutdown closes with 1001 and may not include a JSON error.