Editing SimTX API v24/Limits and errors

{{SimTX API v24 navigation}}
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 ==
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 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 v24/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 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.
|-
| 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 v24/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 v24/Packets/TxReject|TxReject]] with a reason, then close.
|-
| Transmitter request malformed || Close, no reply.
|-
| Transmitter removed || [[SimTX API v24/Packets/TxKick|TxKick]] with a reason, then close.
|-
| Live update refused || [[SimTX API v24/Packets/TxUpdateAck|TxUpdateAck]] with <code>accepted = false</code>; the session continues.
|-
| Control request rate exceeded || Close, no reply.
|-
| 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 v24/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 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.
# '''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 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.
# 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 v24 navbox}}
[[Category:SimTX API v24]]