SimTX API/Packets/Error

Error

Frame	ServerFrame, field 3
Member	error
Direction	Server → client
Session	All roles
Roles	All roles.
Permission	None
Answered by
Answers
Defined in	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 available / ok 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 SessionStatus REJECTED / ENDED.

Definition

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

Fields

#	Field	Type	Description
1	code	ErrorCode	What went wrong. Clients treat unknown codes like ERROR_CODE_UNSPECIFIED.
2	message	string	Human-readable reason. Written for people; do not parse it.
3	request_id	int64	The request_id of the failed request. 0 means the connection as a whole, a protocol violation, after which the server closes the connection.

Which request failed

request_id	Meaning	Afterwards
Nonzero	The request with that id failed. It is a control or moderation request, a TxUpdate, an AntennaPointingUpdate, a ReceiverRetune, a StartMonitor or a 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.

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

Error codes

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

The full table, with advice on retrying, is on Limits and errors.

Examples

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

error_rate_limited (server to client, 38 bytes):

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

error_ephemeris_not_found (server to client, 26 bytes):

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

error_coverage_cancelled (server to client, 49 bytes):

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

See also

• SimTX API/Limits and errors
• SessionStatus