SimTX API v24/Limits and errors

This page collects the limits, timeouts and failure behaviour of the SimTX API game protocol in one place. For account service limits, see Account service.

Session limits

Each server enforces its own limits. The defaults are:

Limit	Whole server	Per client
Sessions (receivers and transmitters)	128	16
Receivers	64	8 per IP address
Transmitters	16	4 per account
Connections of any kind	256	32 per IP address

Operators can change these values, and the public server may use different ones.

• Receiver limits are counted per client IP address. A receiver over a limit is closed without a message.
• Transmitter limits are counted per account. A request over the account's limit receives a TxReject naming the limit. When the server is full, transmitters wait in a queue instead (see TxQueue).
• Account capabilities (game.max_stations.N, game.max_receivers.N, game.max_sessions.N) are checked in addition to the server limits. Both must allow a session. An account without a game.max_stations capability may run 3 transmitters. See SimTX API/Permissions.

Rate and size limits

What	Limit
Control requests	20/s per IP (burst 40), heavy 4/s (burst 12). See Control session.
Transmitter input	1.05 × the declared rate after a burst of about 2 s; excess blocks are discarded.
TxUpdate	One applied update per 250 ms; frequency once per second.
Wideband reception	32 million samples per second per IP, plus a server-wide budget.
SampleBlock	At most 65,536 values.
IQ block	At most 1 MiB.
NEC deck	At most 262,144 bytes.
Transmitter request	At most 263,168 bytes of TLV payload.

Timeouts

Timer	Value	Effect
Handshake and first request	5 s through the public gateway, 15 s direct	Connection closed.
Receiver not reading	5 s	Connection closed.
Transmitter not reading telemetry	5 s	Connection closed.
Transmitter audio input stalled	15 s	Connection closed. Does not apply to IQ sources.
Account lease	About 12 h	Connection closed; reconnect with a new ticket.
Control session idle	None

How errors arrive

Situation	What the client sees
Handshake refused	HandshakeResult with a non-zero status, then close.
Malformed handshake	Close, no reply.
Over a connection limit	Close, no reply.
Receiver request invalid or over a limit	Close, no reply.
Transmitter request refused	TxReject with a reason, then close.
Transmitter request malformed	Close, no reply.
Transmitter removed	TxKick with a reason, then close.
Live update refused	TxUpdateAck with accepted = false; the session continues.
Control request rate exceeded	Close, no reply.
Catalog request refused	CatalogUploadResult or CatalogDeleteResult with a message; the session continues.
Coverage map unavailable	CoverageMapResponse with available = false; the session continues.
Unknown or out-of-place packet	Close, no reply.
Lease expired, account changed	Close, no reply.

There is no goodbye packet. End of stream ends the session.

Diagnosing a silent close

When a connection closes with no explanation, check in this order:

1. Is the decoder aligned? A packet read with one byte too many or too few makes every later packet look like garbage, and the client will report nonsense IDs before the server ever closes anything.
2. Strings. UTF fields have a u16 length; TLV and NEC strings have an i32 length supplied by their container. See Strings.
3. Values. Latitude in −90 to 90, longitude in −180 to 180, finite floats, non-negative noise figure and frequency, positive bandwidth and sample rate, callsign of 1 to 64 printable characters.
4. Packet order. A receiver may send only ReceiverRetune after its request. A control session accepts only control requests.
5. Limits. Too many receivers from one address, a wideband request over budget, or control requests too fast.

Reconnecting

SimTX has no session resumption. After any disconnect:

1. If the connection was authenticated, obtain a new game ticket. Tickets are single use.
2. Reconnect with exponential backoff, for example 1, 2, 4, 8 … seconds up to a minute, with random jitter. A client that reconnects instantly in a loop after a limit rejection will keep being rejected, and may be rate limited by the account service as well.
3. Send the session request again with the same settings.

A transmitter that reconnects is a new station with a new UUID, and may have to queue again.