Clanker: Remove development history and server internals

2026-10-24T17:16:24Z

Remove development history and server internals

← Older revision		Revision as of 17:16, 24 October 2026
Line 12:		Line 12:
	\| file = frames.proto		\| file = frames.proto
	}}		}}
	'''Error''' ~~is the single error frame of protocol v25. It~~ reports a failed control or moderation request, a refused live request on a receiver or transmitter session, or a protocol violation of the connection as a whole~~. It replaces v24's ModerationError, the silent closes of v24, and the <code>available</code> / <code>ok</code> flags of several v24 responses~~.		'''Error''' reports a failed control or moderation request, a refused live request on a receiver or transmitter session, or a protocol violation of the connection as a whole.

	Refusals of a whole session are not reported with Error: a refused start and a session ended by the server arrive as [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>REJECTED</code> / <code>ENDED</code>.		Refusals of a whole session are not reported with Error: a refused start and a session ended by the server arrive as [[SimTX API/Packets/SessionStatus\|SessionStatus]] <code>REJECTED</code> / <code>ENDED</code>.
Line 79:		Line 79:

	== Examples ==		== Examples ==
	Complete frames, including the varint length prefix~~, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>)~~.		Complete frames, including the varint length prefix.

	'''<code>error_rate_limited</code>''' (server to client, 38 bytes):		'''<code>error_rate_limited</code>''' (server to client, 38 bytes):

Clanker: Protocol v25 reference

2026-10-24T16:27:43Z

Protocol v25 reference

New page

{{SimTX API navigation}}
{{SimTX packet
| name = Error
| frame = ServerFrame
| field = 3
| member = error
| direction = s2c
| session = [[SimTX API/Connection and handshake|All roles]]
| roles = All roles.
| permission = None
| group = connection
| file = frames.proto
}}
'''Error''' is the single error frame of protocol v25. It reports a failed control or moderation request, a refused live request on a receiver or transmitter session, or a protocol violation of the connection as a whole. It replaces v24's ModerationError, the silent closes of v24, and the <code>available</code> / <code>ok</code> flags of several v24 responses.

Refusals of a whole session are not reported with Error: a refused start and a session ended by the server arrive as [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>REJECTED</code> / <code>ENDED</code>.

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

== Fields ==
{| class="wikitable"
! # !! Field !! Type !! Description
|-
| 1 || <code>code</code> || [[SimTX API/Data types#ErrorCode|ErrorCode]] || What went wrong. Clients treat unknown codes like <code>ERROR_CODE_UNSPECIFIED</code>.
|-
| 2 || <code>message</code> || <code>string</code> || Human-readable reason. Written for people; do not parse it.
|-
| 3 || <code>request_id</code> || <code>int64</code> || The <code>request_id</code> of the failed request. 0 means the connection as a whole, a protocol violation, after which the server closes the connection.
|}

== Which request failed ==
{| class="wikitable"
! <code>request_id</code> !! Meaning !! Afterwards
|-
| Nonzero || The request with that id failed. It is a control or moderation request, a [[SimTX API/Packets/TxUpdate|TxUpdate]], an [[SimTX API/Packets/AntennaPointingUpdate|AntennaPointingUpdate]], a [[SimTX API/Packets/ReceiverRetune|ReceiverRetune]], a [[SimTX API/Packets/StartMonitor|StartMonitor]] or a [[SimTX API/Packets/StopMonitor|StopMonitor]]. || The session continues.
|-
| 0 || The connection as a whole: a protocol violation or a frame not allowed in this session. || The server closes the connection.
|}

<code>ERROR_CODE_RATE_LIMITED</code> on a control session names the request that overran the limit, but the server closes the connection after it all the same.

== Error codes ==
{| class="wikitable"
! Value !! Name !! Meaning
|-
| 0 || <code>ERROR_CODE_UNSPECIFIED</code> || No specific code: an <code>ENDED</code> session that simply ended. Also how to treat unknown codes.
|-
| 1 || <code>ERROR_CODE_INVALID_REQUEST</code> || Malformed or out-of-range request, or a frame not allowed in this session.
|-
| 2 || <code>ERROR_CODE_UNAUTHENTICATED</code> || Needs an account or a valid ticket.
|-
| 3 || <code>ERROR_CODE_FORBIDDEN</code> || Not allowed, or the ticket's station binding does not match the request.
|-
| 4 || <code>ERROR_CODE_NOT_FOUND</code> || Unknown station, satellite, session or catalog entry.
|-
| 5 || <code>ERROR_CODE_LIMIT_REACHED</code> || Server, address, account or station capacity reached.
|-
| 6 || <code>ERROR_CODE_RATE_LIMITED</code> || Too many requests.
|-
| 7 || <code>ERROR_CODE_UNAVAILABLE</code> || Transient condition: disabled, busy or not reachable.
|-
| 8 || <code>ERROR_CODE_STATION_INACTIVE</code> || The station is deleted or deorbited, or the satellite has reentered.
|-
| 9 || <code>ERROR_CODE_STATION_REQUIRED</code> || Ad-hoc transmitter refused; bind one of your stations.
|-
| 10 || <code>ERROR_CODE_INTERNAL</code> || Server fault.
|-
| 11 || <code>ERROR_CODE_CANCELLED</code> || Superseded by a newer request of the same kind (coverage maps).
|}

The full table, with advice on retrying, is on [[SimTX API/Limits and errors#Error codes|Limits and errors]].

== Examples ==
Complete frames, including the varint length prefix, from the protocol's golden test vectors (<code>protocol/simtx/v25/testdata/frames.json</code>).

'''<code>error_rate_limited</code>''' (server to client, 38 bytes):

<syntaxhighlight lang="text">
25 frame length 37
1A 23 error (Error), 35 bytes
08 06 code = 6 (ERROR_CODE_RATE_LIMITED)
12 1D 43 6F 6E 74 72 6F 6C 20 … message = "Control request rate exceeded"
18 0C request_id = 12
</syntaxhighlight>

'''<code>error_ephemeris_not_found</code>''' (server to client, 26 bytes):

<syntaxhighlight lang="text">
19 frame length 25
1A 17 error (Error), 23 bytes
08 04 code = 4 (ERROR_CODE_NOT_FOUND)
12 11 55 6E 6B 6E 6F 77 6E 20 … message = "Unknown satellite"
18 15 request_id = 21
</syntaxhighlight>

'''<code>error_coverage_cancelled</code>''' (server to client, 49 bytes):

<syntaxhighlight lang="text">
30 frame length 48
1A 2E error (Error), 46 bytes
08 0B code = 11 (ERROR_CODE_CANCELLED)
12 28 50 72 65 64 69 63 74 69 … message = "Prediction superseded by a newer request"
18 2A request_id = 42
</syntaxhighlight>

== See also ==
* [[SimTX API/Limits and errors]]
* [[SimTX API/Packets/SessionStatus|SessionStatus]]

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

SimTX API/Packets/Error - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference