Appendix D: Status Report Messages

Overview

The StatusReport is a core message that encapsulates the result of an operation which a responder sends as a reply for requests sent from an initiator, using a common message of the Secure Channel Protocol (Protocol ID = PROTOCOL_ID_SECURE_CHANNEL).

This section details the standard Status Report message format encoding as Matter Message Format payloads.

D.2. Status Report elements

A Status Report message describes a protocol-specific operation result or status.

The Status Report message SHALL have the following message header values (some of which may be omitted within protocol messages, as per header flag rules), no matter which protocol actually generated the status report:

A Protocol Vendor ID set to 0 (Matter common Vendor ID)
A Protocol ID set to 0x0000 (PROTOCOL_ID_SECURE_CHANNEL)
A Protocol Opcode set to 0x40 (StatusReport)

The report message’s Application Payload SHALL consist of:

A mandatory GENERAL CODE field, providing a general description of the status being
A mandatory PROTOCOL SPECIFIC STATUS field, providing additional details
An optional protocol-specific data section that MAY include any additional information that a protocol requires
- Individual protocols define the contents of this data section and how it is handled

D.3. Message Format

Length	Octets 0	1
Structure, little-endian
2 octets	GeneralCode
4 octets	ProtocolId of Protocol-Specific Status
	. . .
2 octets	ProtocolCode of Protocol-Specific Status
Variable	Optional ProtocolData for protocol-specific additional details, MAY be empty

General status codes (GeneralCode)

General status codes conveyed in the GeneralCode field are uniform codes that convey both success and failures.

The following general status codes are defined:

Code	Numeric Value	Description
SUCCESS	0	Operation completed successfully.
FAILURE	1	Generic failure, additional details may be included in the protocol specific status.
BAD_PRECONDITION	2	Operation was rejected by the system because the sys tem is in an invalid state.
OUT_OF_RANGE	3	A value was out of a required range
BAD_REQUEST	4	A request was unrecognized or malformed
UNSUPPORTED	5	An unrecognized or unsupported request was received
UNEXPECTED	6	A request was not expected at this time
RESOURCE_EXHAUSTED	7	Insufficient resources to process the given request
BUSY	8	Device is busy and cannot handle this request at this time
TIMEOUT	9	A timeout occurred
CONTINUE	10	Context-specific signal to proceed
ABORTED	11	Failure, may be due to a concurrency error.
INVALID_ARGUMENT	12	An invalid/unsupported argument was provided
NOT_FOUND	13	Some requested entity was not found
ALREADY_EXISTS	14	The sender attempted to create something that already exists
PERMISSION_DENIED	15	The sender does not have sufficient permissions to exe cute the requested operations.
DATA_LOSS	16	Unrecoverable data loss or corruption has occurred.

If none of the specific codes above fits for application usage, a protocol SHALL use FAILURE and provide more information encoded in the ProtocolId and ProtocolCode subfields.

Protocol-specific codes (ProtocolId and ProtocolCode)

The protocol-specific portion of StatusReport messages is composed of a fully-qualified ProtocolId

which qualifies the subsequent ProtocolCode space.

The ProtocolId is encoded as a 32 bit value of Protocol Vendor ID (upper 16 bits) and Protocol ID under that Protocol Vendor ID (lower 16 bits), similarly to how message Protocol ID and Protocol

Vendor ID are encoded in the Protocol Header.

The following rules apply to the encoding of the ProtocolCode protocol-specific field:

ProtocolCode value 0x0000 SHALL be reserved for use as success placeholder when either a Gen eralCode of SUCCESS (0) or CONTINUE (10) are present.
ProtocolCode value 0xFFFF SHALL be reserved to indicate that no additional protocol-specific status code is
When the GeneralCode is FAILURE, the ProtocolCode value of 0xFFFF SHOULD NOT be used, since the conveyance of specific error codes assists in
ProtocolCode values 0x0001 through 0xFFFE SHALL be used to convey protocol-specific status indications.

Since protocol-specific status reports are meant to convey more information than generic codes, it is RECOMMENDED to always use a specific ProtocolCode value, rather than 0xFFFF, unless there are no additional details to convey.

Protocol-specific data (ProtocolData)

The ProtocolData portion of the StatusReport message is composed of all data beyond the Protocol Code field. If a StatusReport message of size N octets is received, the first 8 octets of payload encode the GeneralCode, ProtocolId and ProtocolCode, while the remaining N – 8 bytes represent the proto col-specific ProtocolData.

Encoding of the ProtocolData portion of the payload depends on the ProtocolId and potentially Pro tocolCode. To decode this data, the ProtocolId has to be examined and decoding SHALL be done according to that protocol specification. For example:

A vendor-specific protocol would encode additional custom error metadata in the ProtocolData.
The Bulk transfer (BDX) protocol does not require additional error information and will always have ProtocolData

Presenting StatusReport messages in protocol specifications

In order to simplify referring to StatusReport messages, the following mnemonic encoding will be used in the descriptive text for a given protocol.

References to StatusReport messages take one of the following forms:

No ProtocolData present:
- StatusReport(GeneralCode: <value>, ProtocolId: <value>, ProtocolCode: <value>)
  - Example 1: StatusReport(GeneralCode: FAILURE, ProtocolId: BDX, ProtocolCode: START_OFFSET_NOT_SUPPORTED)
    - Encodes as: 01 00 02 00 00 00 52 00

Example 2: StatusReport(GeneralCode: SUCCESS, ProtocolId: {VendorID=0xFFF1, Proto colId=0xAABB}, ProtocolCode: 0)
- Encodes as: 00 00 BB AA F1 FF 00 00
Additional ProtocolData present:
- StatusReport(GeneralCode: <value>, ProtocolId: <value>, ProtocolCode: <value>, Protocol Data: <value>)
  - Example: StatusReport(GeneralCode: FAILURE, ProtocolId: {VendorID=0xFFF1, Proto colId=0xAABB}, ProtocolCode: 9921, ProtocolData: [0x55, 0x66, 0xEE, 0xFF])

Encodes as: 01 00 BB AA F1 FF