Editing SimTX API/Packets/Error

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

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

'''<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]]