Server service messages

The server sends service messages instead of a response when it cannot parse a request: the message is not JSON, the JSON has no cmd field, or there is no such command. These messages have no status and error_code fields: the message name itself describes the error.

Message	When it arrives	operation_id
json_parse_error	A text message is not JSON or not UTF-8	No
invalid_req	The JSON is not an object, or is an object without a cmd field	No
invalid_command_req	cmd holds an unknown command	From the request

Current ONS version

The server does not send the die_connection_close message from the v0.17 description. When a connection times out, the server closes it without a message and without a Close frame — see ping_req.

json_parse_error

Arrives if a text message cannot be parsed as JSON or is not UTF-8 encoded. The server sends it even before the connection is confirmed (connected).

{
    "cmd": "json_parse_error"
}

What to do. Make sure the client sends valid JSON as a UTF-8 text message. The response has no operation_id, so it can be matched with a request only by the order in which requests were sent — validate JSON before sending.

invalid_req

Arrives if the message is valid JSON but is not an object (for example, an array or a string), or is an object without a cmd field.

{
    "cmd": "invalid_req"
}

What to do. Send every request as a JSON object with a cmd field. The server does not return the operation_id of such a request.

invalid_command_req

Arrives if cmd holds a command the server does not have, e.g. because of a typo in the name. The same message arrives if connections_list could not get the list of connections.

{
    "cmd": "invalid_command_req",
    "operation_id": "abc"
}

Field	Type	Description
cmd	string	invalid_command_req
operation_id	string	Value from the request; an empty string if there was none

What to do. Check the command name. Note that some request names have no _req suffix, e.g. connections_list, connection_kill, set_alive_timeout.

When the server does not respond at all

• The request was sent before the connected message with status: 1 — the server skips it. Wait for connected, see Connection.
• The message was sent as a binary frame — the server accepts only text frames.
• cmd is not a string but a number, null, an object or an array.

Messages the server sends on its own

Message	When	Description
connected	Right after connecting	Connection
consume_resp	After connected, if automatic subscription is enabled in the application settings	consume_req
realtime_data	For every uplink, if the connection is subscribed	consume_req
downlink_status	When the status of a sent frame changes, if the subscription was made with "downlink_status": true	Sending data to a device

See also

• Connection — how to connect and when the server closes the connection.