Error detection

When maintaining a connected Live client, clients should monitor their connection for errors.

There are three main ways in which a session can enter an error state:

  • Hung connection: The client is not receiving any data from the gateway
  • Disconnect without error: The client is explicitly disconnected by the gateway, without receiving an error message
  • Disconnect with error: The client is explicitly disconnected by the gateway. Immediately prior to being disconnected, the client will receive an error record

Hung connection

To detect hung connections, clients are instructed to make use of system heartbeats. Clients can configure a heartbeat interval when creating the Live client by setting the heartbeat_interval_s parameter. If the heartbeat interval is not set by the client, it will default to 30 seconds.

Once a session is started, if no data is sent by the gateway for the entirety of a heartbeat interval, the gateway will send a system message to the client to indicate a heartbeat. If the gateway is regularly sending other messages to the client (for example, MboMsg), heartbeats will not be sent.

Once a session is started, if a client does not receive any messages from the gateway for the duration of one heartbeat interval plus ten seconds, the session can be considered hung. Clients are instructed to disconnect from the gateway and reconnect upon detecting hung connections.

Clients with unstable internet connections may need larger intervals than ten seconds to ensure the connection is truly hung, as opposed to merely delayed.

Disconnect without error

From the point of view of the Live client, a disconnect is detected when the underlying TCP session is closed. When using Live.block_for_close or Live.wait_for_close, an exception will be raised if the TCP session was closed without an error. Upon being disconnected, clients are instructed to wait one second and initiate a new connection. Waiting too short an interval to reconnect may trigger the gateway's rate limiter.

See also

Connection limits for more details.

Disconnect with error

From the point of view of the Live client, a disconnect with error is detected when the underlying TCP session is closed after an ErrorMsg or a API error response is received. Any ErrorMsg records received by the client can be consumed by the application, such as when iterating or using a callback with Live.add_callback. When using Live.block_for_close or Live.wait_for_close, any ErrorMsg records received will be raised in an exception.

Clients disconnected with an error are instructed to not reconnect automatically. In the vast majority of cases, reconnecting and resubscribing with the same parameters will lead to the same errors being received again. The error sent to the client will indicate the issue to be fixed prior to resubscribing.