Editing SimTX API/Limits and errors

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

== Error model ==
Every failure arrives in one of these ways:

{| class="wikitable"
! What failed !! How it arrives !! Afterwards
|-
| The hello || [[SimTX API/Packets/ServerHello|ServerHello]] with a status other than <code>ACCEPTED</code> and a message || The connection closes.
|-
| A receiver or transmitter start || [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>REJECTED</code> with <code>code</code> and <code>reason</code> || The connection closes.
|-
| A running session, stopped by the server || [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>ENDED</code> with <code>code</code> and <code>reason</code> || The connection closes.
|-
| A request: control, catalog, moderation, ephemeris, passes, monitor, pointing, retune || [[SimTX API/Packets/Error|Error]] with <code>code</code>, <code>message</code> and the request's <code>request_id</code> || The session continues.
|-
| A transmitter live update || [[SimTX API/Packets/TxUpdateAck|TxUpdateAck]] with <code>accepted = false</code> for the refused fields || The session continues.
|-
| A protocol violation: a malformed frame, a frame not allowed in the session, values out of range || [[SimTX API/Packets/Error|Error]] <code>INVALID_REQUEST</code>, <code>request_id</code> 0, where the server can still send it || The connection closes.
|-
| A control rate limit || [[SimTX API/Packets/Error|Error]] <code>RATE_LIMITED</code> || The connection closes.
|}

<syntaxhighlight lang="protobuf">
message Error {
  ErrorCode code = 1;
  string message = 2;
  int64 request_id = 3;
}
</syntaxhighlight>

== Error codes ==
The same [[SimTX API/Data types#ErrorCode|ErrorCode]] is used by Error and by SessionStatus.

{| class="wikitable"
! Value !! Code !! Meaning !! Retry the same request?
|-
| 0 || <code>ERROR_CODE_UNSPECIFIED</code> || No specific code, for example an <code>ENDED</code> session that simply ended. Unknown codes are treated the same way. || Depends on the reason
|-
| 1 || <code>ERROR_CODE_INVALID_REQUEST</code> || Malformed or out-of-range request, or a frame not allowed in this session. || No; fix the request
|-
| 2 || <code>ERROR_CODE_UNAUTHENTICATED</code> || Needs an account or a valid ticket. || After signing in
|-
| 3 || <code>ERROR_CODE_FORBIDDEN</code> || Not allowed, or the ticket's station binding does not match. || No
|-
| 4 || <code>ERROR_CODE_NOT_FOUND</code> || Unknown station, satellite, session or catalog entry. || No
|-
| 5 || <code>ERROR_CODE_LIMIT_REACHED</code> || Server, address, account or station capacity. || Later
|-
| 6 || <code>ERROR_CODE_RATE_LIMITED</code> || Too many requests. || Later, more slowly
|-
| 7 || <code>ERROR_CODE_UNAVAILABLE</code> || A transient condition: disabled, busy or not reachable. || Yes, with backoff
|-
| 8 || <code>ERROR_CODE_STATION_INACTIVE</code> || The station is deleted or deorbited, or the satellite has reentered. || No
|-
| 9 || <code>ERROR_CODE_STATION_REQUIRED</code> || Ad-hoc transmitter refused; bind one of your stations. || No
|-
| 10 || <code>ERROR_CODE_INTERNAL</code> || Server fault. || Yes, with backoff
|-
| 11 || <code>ERROR_CODE_CANCELLED</code> || Superseded by a newer request of the same kind (coverage maps). || No; the newer request is answered
|}

The <code>message</code> or <code>reason</code> is human-readable English. Show it to the user, but branch on the code; wording may change.

== 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.

* '''Receiver limits''' are counted per client IP address. A start over a limit is refused with <code>LIMIT_REACHED</code>.
* '''Transmitter limits''' are counted per account. When the ''server'' is full, transmitters wait in a queue instead (see [[SimTX API/Packets/TxQueue|TxQueue]]), unless the account holds <code>session.queue_skip</code>.
* '''Account capabilities''' (<code>game.max_stations.N</code>, transmitters on air at once; <code>game.max_receivers.N</code>; <code>game.max_sessions.N</code>; <code>tx.pa_limit.N</code>) are checked in addition to the server limits. See [[SimTX API/Permissions]].
* '''Station limits''' (<code>maxSessions</code>, <code>maxTransmitters</code>, <code>maxReceivers</code>, set by the owner and clamped by <code>game.station_sessions.N</code>) apply to station-bound sessions. The owner is not counted against the station's receiver limit. See [[SimTX API/Stations#Limits|Stations]].

== Rate and size limits ==
{| class="wikitable"
! What !! Limit
|-
| Control requests || 20/s per address (burst 40), heavy 4/s (burst 12); server-wide 200/s and 40/s. 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 address, plus a server-wide budget.
|-
| Frame || At most 16 MiB; the hello at most 64 KiB.
|-
| Frame shape || At most 16,384 (client frames) or 2,097,152 (server frames) nested messages, repeated string, bytes and message elements, and unknown fields; nesting at most 32 deep. See [[SimTX API/Framing#Size and shape limits|Framing]].
|-
| SampleBlock || At most 65,536 values.
|-
| NEC deck || At most 262,144 bytes.
|-
| Callsign || 1 to 64 printable characters.
|-
| Ephemeris || At most 3,600 samples per request.
|-
| Pass prediction || A window of at most 7 days.
|-
| Coverage map || 4 to 72 columns, 2 to 36 rows.
|}

== Timeouts ==
{| class="wikitable"
! Timer !! Value !! Effect
|-
| Preface, hello and start || 5 s || Connection closed.
|-
| No hello at all || 20 s || Connection closed.
|-
| Receiver not reading || 5 s || Connection closed.
|-
| Transmitter not reading telemetry || 5 s || Connection closed.
|-
| Transmitter audio input stalled || 15 s || Session ended. Does not apply to IQ sources.
|-
| Account lease || About 12 h || Connection closed; reconnect with a new ticket.
|-
| Control session idle || None ||
|}

== Diagnosing a refused session ==
When a start is refused or a connection closes, check in this order:
# '''The code and reason.''' A SessionStatus or Error says what was wrong. Log both.
# '''Framing.''' A wrong length prefix or a missing preface makes every later byte look like garbage. Test the codec against the examples on the packet pages first.
# '''Encoding.''' Protobuf scalars are little-endian; IQ sample bytes are big-endian. Strings are UTF-8 with a varint length. UUIDs are 16 raw bytes, not text.
# '''Values.''' Latitude in −90 to 90, longitude in −180 to 180, finite floats, non-negative noise figure and frequency, positive bandwidth and sample rate, a callsign of 1 to 64 printable characters, exactly one site member.
# '''Frame order.''' A receiver may send only ReceiverRetune, AntennaPointingUpdate and Ping after its start. A control session accepts only control requests.
# '''Tickets and bindings.''' A ticket is single-use and valid for 60 seconds, for one server and one role; a station-bound start must match the station, antenna and rig of its ticket.
# '''Limits.''' Too many receivers from one address, a wideband request over budget, a full station, 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 and so on up to a minute, with random jitter.
# Send the start again with the same settings.

A reconnected session is a new session with a new <code>session_id</code>, and a transmitter may have to queue again.

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