# Connection lifecycle

Source: [Official documentation](<https://newlistings.pro/docs/v2/connection-lifecycle>)

## Wait for READY

After connection admission succeeds, the server sends one [`READY` message](<https://newlistings.pro/docs/v2/connection-lifecycle#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:

```json
{
  "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](<https://newlistings.pro/docs/v2/rate-limits#open-connections>). |
| `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](<https://newlistings.pro/docs/v2/code-examples>) for handling both HTTP upgrade failures and WebSocket closes.

Reconnecting resumes live events. Recover missed Full events through [history](<https://newlistings.pro/docs/v2/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.



**Note**

A network failure can end the connection before an application error arrives. Always handle the WebSocket close event as well as JSON error messages. If you receive `1008` without a JSON error, pause retries and check your key, connection limits, and client behavior.