Overview
RAIDA responses still use a fixed 32-byte header. The newer 48-byte request-side preamble does not change the response header size. Clients should parse the response header first, then interpret the body according to the command family and status byte.
Parsing rules
- Status is byte 2 of the response header.
- Echo bytes let the client match the response to the originating request.
- The signature/challenge block is part of the header, not the body.
32-byte response header layout
RI SH SS CG UD UD EC EC
RS SZ SZ SZ ET ET ET ET
HC HC HC HC HC HC HC HC
HC HC HC HC HC HC HC HC
| Offset |
Bytes |
Name |
Purpose |
| 0 | 1 | RI | Responding RAIDA index. |
| 1 | 1 | SH | Responding shard identifier. |
| 2 | 1 | SS | Response status code. |
| 3 | 1 | CG | Command group echoed back by the server. |
| 4-5 | 2 | UD | UDP framing/count metadata. |
| 6-7 | 2 | EC | Client echo bytes from the request header. |
| 8 | 1 | RS | Reserved byte. |
| 9-11 | 3 | SZ | Response body size. |
| 12-15 | 4 | ET | Execution time. |
| 16-31 | 16 | HC | Header signature / challenge response material. |
Field reference
| Field |
Developer note |
| Status | This is the primary dispatch point for client handling. |
| Body size | Use this to know whether a mixed-status bitfield, ticket, object, or other payload should follow. |
| Execution time | Useful for telemetry and RAIDA health scoring, but not for protocol correctness. |
| Header challenge/signature | Use when the command family requires response verification against the original request challenge. |
Common success statuses
| Code |
Name |
Typical meaning |
| 241 | ALL_PASS | All requested items passed. |
| 242 | ALL_FAIL | All requested items failed. |
| 243 | MIXED | Mixed result set. The body usually carries a bitfield or command-specific detail. |
| 244 | TEST_GOOD | Loopback/diagnostic success. |
| 250 | SUCCESS | Generic success for non-auth batch flows. |
Common error statuses
| Code |
Name |
Meaning |
| 5 | INVALID_COMMAND_GROUP | Unknown command group. |
| 6 | INVALID_COMMAND | Unknown command code. |
| 16 | INVALID_PACKET_LENGTH | Header or body length is not valid. |
| 27 | INVALID_ENCRYPTION_CODE | Unsupported request encryption type. |
| 33 | INVALID_EOF | Missing 0x3E 0x3E terminator. |
| 34 | INVALID_ENCRYPTION | The encrypted body could not be validated or decrypted. |
| 37 | INVALID_CRC | Challenge CRC mismatch. |
| 38 | ADMIN_AUTH | Admin authentication failed. |
| 39 | COINS_NOT_DIV | Requested change operation is not denomination-safe. |
| 40 | INVALID_SN_OR_DENOMINATION | Invalid denomination or serial number. |
| 194 | FILESYSTEM | Storage/object operation failed at the filesystem layer. |
| 198 | INVALID_PARAMETER | One or more supplied parameters are invalid. |
| 199 | INVALID_PAN | Invalid proposed authenticity number. |
| 200 | INVALID_AN | Invalid authenticity number. |
| 201 | FILE_EXISTS | Object or file already exists. |
| 202 | FILE_NOT_EXIST | Requested object or file was not found. |
| 206 | RAIDA_TIMEOUT | Repair/healing timed out. |
| 207 | INVALID_HMAC | HMAC validation failed. |
| 208 | FIND_NEITHER | Neither current AN nor PAN matched. |
| 209 | FIND_ALL_AN | All matches were against the current AN. |
| 210 | FIND_ALL_PAN | All matches were against the PAN. |
| 211 | FIND_MIXED | The result set contains both AN and PAN matches. |
| 217 | RAIDA_CONNECTION | The requested RAIDA connection failed at the network layer. |
| 252-255 | INTERNAL / TEMPORARY / BUSY / PERMANENT | Server-side failure classes. |
Implementation notes
Client handling recommendations
- Treat 241, 242, 243, and 250 as the main success-family statuses.
- Do not collapse
INVALID_HMAC (207) into connection failures.
- Do not collapse
RAIDA_CONNECTION (217) into cryptographic failures.
- Always interpret the response body in combination with the command family and status byte.
