A session outlives any one WebSocket. When the socket drops, reconnect to the same control_url, repeat the handshake, and carry on. The Python SDK does this for you: when the socket drops, the next call (and any call cut off by the drop) reopens it, backing off for about 15 seconds, and re-sends with the call’s idempotency key. It stops on a 403, the session having ended. Scripts (evaluate) are keyed only when you pass a key, so a keyless script cut off by a drop runs again. A call cut off by a stalled connection rather than a closed one fails with a timeout and is not re-sent; the next call redials once the socket’s keepalive has closed it. Each re-send gets the call’s full timeout.

Classify the close

Reconnect and watch the HTTP status of the upgrade:
StatusMeaningDo
101Connected.Handshake and carry on.
401The token is bad or expired.Get a fresh control_url.
403The session is no longer active.Stop: it has ended.

Resume with a cursor

By default a new socket starts at the live tail of the stream: replies to commands sent before the drop are lost. To get them, opt in to checkpoints:
  1. Attach with &resume=1. The session then sends a Halyard.cursor notification after each batch of frames: { "method": "Halyard.cursor", "params": { "cursor": "..." } }.
  2. Keep the latest cursor. It is opaque: never parse it.
  3. After a drop, reattach with &resume=1&cursor=<latest>. Delivery restarts strictly after that checkpoint, so frames after it are delivered again. Match replies by id and ignore ones you’ve already handled.
If the cursor has fallen out of the stream, you get Halyard.resyncRequired instead: some frames are gone, so re-read the state you need (Page.getInfo, Target.getTargets).

Idempotency keys

A command that changes the page and was in flight when the socket dropped may or may not have run. Mutating commands take an idempotencyKey: the session remembers each key’s response, and a repeated key returns the recorded response (with the new id) without acting again.
{ "id": 9, "method": "Locator.click", "params": {
  "locator": { "kind": "role", "role": "button", "name": "Pay" },
  "idempotencyKey": "pay-7f3c"
} }
Use a fresh key for each logical command, and reuse it verbatim only when re-sending that same command after a reconnect. Keys apply to Keyboard, Pointer (except move), the Locator actions, evaluate and dispatchEvent, the navigating Page methods and setContent, and Target create, close and activate. Reads, waits, hovers and scrolls into view take no key: they are safe to repeat.