SimTX API v24/Limits and errors - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:13:44Z

Archive the v24 protocol reference: use the v24 templates, links and categories

Clanker: Clanker moved page SimTX API/Limits and errors to SimTX API v24/Limits and errors: Archive the v24 protocol reference

2026-10-24T16:12:44Z

Clanker moved page SimTX API/Limits and errors to SimTX API v24/Limits and errors: Archive the v24 protocol reference

← Older revision	Revision as of 16:12, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:49:20Z

SimTX API documentation

New page

{{SimTX API navigation}}
This page collects the limits, timeouts and failure behaviour of the [[SimTX API]] game protocol in one place. For account service limits, see [[SimTX API/Account service#Rate limits|Account service]].

== Session limits ==
Each server enforces its own limits. The defaults are:

{| class="wikitable"
! 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 [[SimTX API/Packets/TxReject|TxReject]] naming the limit. When the ''server'' is full, transmitters wait in a queue instead (see [[SimTX API/Packets/TxQueue|TxQueue]]).
* '''Account capabilities''' (<code>game.max_stations.N</code>, <code>game.max_receivers.N</code>, <code>game.max_sessions.N</code>) are checked in addition to the server limits. Both must allow a session. An account without a <code>game.max_stations</code> capability may run 3 transmitters. See [[SimTX API/Permissions]].

== Rate and size limits ==
{| class="wikitable"
! What !! Limit
|-
| Control requests || 20/s per IP (burst 40), heavy 4/s (burst 12). See [[SimTX API/Control session#Rate limits|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 ==
{| class="wikitable"
! 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 ==
{| class="wikitable"
! Situation !! What the client sees
|-
| Handshake refused || [[SimTX API/Packets/HandshakeResult|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 || [[SimTX API/Packets/TxReject|TxReject]] with a reason, then close.
|-
| Transmitter request malformed || Close, no reply.
|-
| Transmitter removed || [[SimTX API/Packets/TxKick|TxKick]] with a reason, then close.
|-
| Live update refused || [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]] with <code>accepted = false</code>; the session continues.
|-
| Control request rate exceeded || Close, no reply.
|-
| Catalog request refused || [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] or [[SimTX API/Packets/CatalogDeleteResult|CatalogDeleteResult]] with a message; the session continues.
|-
| Coverage map unavailable || [[SimTX API/Packets/CoverageMapResponse|CoverageMapResponse]] with <code>available = false</code>; 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:
# '''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.
# '''Strings.''' <code>UTF</code> fields have a <code>u16</code> length; TLV and NEC strings have an <code>i32</code> length supplied by their container. See [[SimTX API/Data types#Strings|Strings]].
# '''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.
# '''Packet order.''' A receiver may send only ReceiverRetune after its request. A control session accepts only control requests.
# '''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:
# If the connection was authenticated, obtain a '''new''' [[SimTX API/Game tickets|game ticket]]. Tickets are single use.
# 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.
# 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.

{{SimTX API navbox}}
[[Category:SimTX API]]

← Older revision		Revision as of 16:13, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	This page collects the limits, timeouts and failure behaviour of the [[SimTX API]] game protocol in one place. For account service limits, see [[SimTX API/Account service#Rate limits\|Account service]].		This page collects the limits, timeouts and failure behaviour of the [[SimTX API v24]] game protocol in one place. For account service limits, see [[SimTX API v24/Account service#Rate limits\|Account service]].

	== Session limits ==		== Session limits ==
Line 20:		Line 20:

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

	== Rate and size limits ==		== Rate and size limits ==
Line 27:		Line 27:
	! What !! Limit		! What !! Limit
	\|-		\|-
	\| Control requests \|\| 20/s per IP (burst 40), heavy 4/s (burst 12). See [[SimTX API/Control session#Rate limits\|Control session]].		\| Control requests \|\| 20/s per IP (burst 40), heavy 4/s (burst 12). See [[SimTX API v24/Control session#Rate limits\|Control session]].
	\|-		\|-
	\| Transmitter input \|\| 1.05 × the declared rate after a burst of about 2 s; excess blocks are discarded.		\| Transmitter input \|\| 1.05 × the declared rate after a burst of about 2 s; excess blocks are discarded.
Line 65:		Line 65:
	! Situation !! What the client sees		! Situation !! What the client sees
	\|-		\|-
	\| Handshake refused \|\| [[SimTX API/Packets/HandshakeResult\|HandshakeResult]] with a non-zero status, then close.		\| Handshake refused \|\| [[SimTX API v24/Packets/HandshakeResult\|HandshakeResult]] with a non-zero status, then close.
	\|-		\|-
	\| Malformed handshake \|\| Close, no reply.		\| Malformed handshake \|\| Close, no reply.
Line 73:		Line 73:
	\| Receiver request invalid or over a limit \|\| Close, no reply.		\| Receiver request invalid or over a limit \|\| Close, no reply.
	\|-		\|-
	\| Transmitter request refused \|\| [[SimTX API/Packets/TxReject\|TxReject]] with a reason, then close.		\| Transmitter request refused \|\| [[SimTX API v24/Packets/TxReject\|TxReject]] with a reason, then close.
	\|-		\|-
	\| Transmitter request malformed \|\| Close, no reply.		\| Transmitter request malformed \|\| Close, no reply.
	\|-		\|-
	\| Transmitter removed \|\| [[SimTX API/Packets/TxKick\|TxKick]] with a reason, then close.		\| Transmitter removed \|\| [[SimTX API v24/Packets/TxKick\|TxKick]] with a reason, then close.
	\|-		\|-
	\| Live update refused \|\| [[SimTX API/Packets/TxUpdateAck\|TxUpdateAck]] with <code>accepted = false</code>; the session continues.		\| Live update refused \|\| [[SimTX API v24/Packets/TxUpdateAck\|TxUpdateAck]] with <code>accepted = false</code>; the session continues.
	\|-		\|-
	\| Control request rate exceeded \|\| Close, no reply.		\| Control request rate exceeded \|\| Close, no reply.
	\|-		\|-
	\| Catalog request refused \|\| [[SimTX API/Packets/CatalogUploadResult\|CatalogUploadResult]] or [[SimTX API/Packets/CatalogDeleteResult\|CatalogDeleteResult]] with a message; the session continues.		\| Catalog request refused \|\| [[SimTX API v24/Packets/CatalogUploadResult\|CatalogUploadResult]] or [[SimTX API v24/Packets/CatalogDeleteResult\|CatalogDeleteResult]] with a message; the session continues.
	\|-		\|-
	\| Coverage map unavailable \|\| [[SimTX API/Packets/CoverageMapResponse\|CoverageMapResponse]] with <code>available = false</code>; the session continues.		\| Coverage map unavailable \|\| [[SimTX API v24/Packets/CoverageMapResponse\|CoverageMapResponse]] with <code>available = false</code>; the session continues.
	\|-		\|-
	\| Unknown or out-of-place packet \|\| Close, no reply.		\| Unknown or out-of-place packet \|\| Close, no reply.
Line 97:		Line 97:
	When a connection closes with no explanation, check in this order:		When a connection closes with no explanation, check in this order:
	# '''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.		# '''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.
	# '''Strings.''' <code>UTF</code> fields have a <code>u16</code> length; TLV and NEC strings have an <code>i32</code> length supplied by their container. See [[SimTX API/Data types#Strings\|Strings]].		# '''Strings.''' <code>UTF</code> fields have a <code>u16</code> length; TLV and NEC strings have an <code>i32</code> length supplied by their container. See [[SimTX API v24/Data types#Strings\|Strings]].
	# '''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.		# '''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.
	# '''Packet order.''' A receiver may send only ReceiverRetune after its request. A control session accepts only control requests.		# '''Packet order.''' A receiver may send only ReceiverRetune after its request. A control session accepts only control requests.
Line 104:		Line 104:
	== Reconnecting ==		== Reconnecting ==
	SimTX has no session resumption. After any disconnect:		SimTX has no session resumption. After any disconnect:
	# If the connection was authenticated, obtain a '''new''' [[SimTX API/Game tickets\|game ticket]]. Tickets are single use.		# If the connection was authenticated, obtain a '''new''' [[SimTX API v24/Game tickets\|game ticket]]. Tickets are single use.
	# 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.		# 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.
	# Send the session request again with the same settings.		# Send the session request again with the same settings.
Line 110:		Line 110:
	A transmitter that reconnects is a new station with a new UUID, and may have to queue again.		A transmitter that reconnects is a new station with a new UUID, and may have to queue again.

	{{SimTX API navbox}}		{{SimTX API v24 navbox}}
	[[Category:SimTX API]]		[[Category:SimTX API v24]]