SimTX API/Limits and errors

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 Account service.

Error model

Every failure arrives in one of these ways:

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

message Error {
  ErrorCode code = 1;
  string message = 2;
  int64 request_id = 3;
}

Error codes

The same ErrorCode is used by Error and by SessionStatus.

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

The message or reason 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:

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 LIMIT_REACHED.
• Transmitter limits are counted per account. When the server is full, transmitters wait in a queue instead (see TxQueue), unless the account holds session.queue_skip.
• Account capabilities (game.max_stations.N, transmitters on air at once; game.max_receivers.N; game.max_sessions.N; tx.pa_limit.N) are checked in addition to the server limits. See SimTX API/Permissions.
• Station limits (maxSessions, maxTransmitters, maxReceivers, set by the owner and clamped by game.station_sessions.N) apply to station-bound sessions. The owner is not counted against the station's receiver limit. See Stations.

Rate and size limits

What	Limit
Control requests	20/s per address (burst 40), heavy 4/s (burst 12); server-wide 200/s and 40/s. 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 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 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

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:

1. The code and reason. A SessionStatus or Error says what was wrong. Log both.
2. 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.
3. 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.
4. 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.
5. Frame order. A receiver may send only ReceiverRetune, AntennaPointingUpdate and Ping after its start. A control session accepts only control requests.
6. 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.
7. 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:

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 and so on up to a minute, with random jitter.
3. Send the start again with the same settings.

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