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

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