This section defines standard error codes for PALISADE protocol errors.
14.1 Error Code Format
Error codes are 16-bit unsigned integers transmitted in error response messages.
struct ErrorResponse {
u16 error_code;
u16 details_len;
opaque details[details_len]; // Optional human-readable description
}Wire Format (ABNF):
ErrorResponse = error_code details_len details
error_code = 2OCTET ; Big-endian u16
details_len = 2OCTET ; Big-endian u16 (length of details)
details = *OCTET ; Variable length human-readable description
14.2 Error Code Ranges
| Range | Category |
|---|
0x0000 | ErrorNone (No error) |
0x0100 - 0x01FF | Handshake errors |
0x0200 - 0x02FF | Session errors |
0x0300 - 0x03FF | Data plane errors |
0x0400 - 0x04FF | Resumption errors |
0x0500 - 0x05FF | Migration errors |
0x0600 - 0x06FF | Control frame errors |
0xFF00 - 0xFFFF | Generic errors |
14.3 Defined Error Codes
Handshake Errors (0x0100 - 0x01FF)
| Code | Name | Description | Fatal |
|---|
0x0100 | ErrorInvalidVersion | Unsupported protocol version | Yes |
0x0101 | ErrorUnsupportedKEM | No mutually supported KEM algorithm | Yes |
0x0102 | ErrorUnsupportedSignature | No mutually supported signature algorithm | Yes |
0x0103 | ErrorUnsupportedAEAD | No mutually supported AEAD algorithm | Yes |
0x0104 | ErrorInvalidClientHello | Malformed ClientHello message | Yes |
0x0105 | ErrorInvalidServerHello | Malformed ServerHello message | Yes |
0x0106 | ErrorSignatureVerifyFailed | Signature verification failed | Yes |
0x0107 | ErrorCertificateInvalid | Invalid or untrusted certificate | Yes |
0x0108 | ErrorKEMDecapFailed | KEM decapsulation failed | Yes |
Session Errors (0x0200 - 0x02FF)
| Code | Name | Description | Fatal |
|---|
0x0200 | ErrorSessionNotFound | Session identifier not found | No |
0x0201 | ErrorSessionExpired | Session has expired | Yes |
0x0202 | ErrorSessionLimitExceeded | Maximum concurrent sessions exceeded | No |
Data Plane Errors (0x0300 - 0x03FF)
| Code | Name | Description | Fatal |
|---|
0x0300 | ErrorAEADDecryptFailed | AEAD authentication tag verification failed | No |
0x0301 | ErrorInvalidEpoch | Packet epoch does not match current epoch | No |
0x0302 | ErrorSequenceExhausted | Sequence number space exhausted, rekey required | Yes |
0x0303 | ErrorReplayDetected | Replayed packet detected (sequence seen before) | No |
0x0304 | ErrorTimestampInvalid | Packet timestamp outside acceptable window | No |
0x0305 | ErrorPacketTooLarge | Packet or handshake message exceeds maximum allowed size (128,000 bytes for handshake messages, 65,535 bytes for data packets) | No |
Resumption Errors (0x0400 - 0x04FF)
| Code | Name | Description | Fatal |
|---|
0x0400 | ErrorTicketInvalid | Resumption ticket signature or decryption failed | Yes |
0x0401 | ErrorTicketExpired | Resumption ticket past expiration time | Yes |
0x0402 | ErrorTicketAlreadyUsed | Resumption ticket already consumed | Yes |
0x0403 | ErrorEarlyDataRejected | 0-RTT early data not accepted by server | No |
Migration Errors (0x0500 - 0x05FF)
| Code | Name | Description | Fatal |
|---|
0x0500 | ErrorMigrationFailed | Migration request failed | No |
0x0501 | ErrorMigrationEpochMismatch | MIGRATE frame epoch does not match current | No |
0x0502 | ErrorMigrationStaleTimestamp | MIGRATE frame timestamp too old | No |
0x0503 | ErrorInvalidMigrationReason | MIGRATE frame invalid reason code | No |
0x0504 | ErrorMigrationNonceReused | MIGRATE frame nonce matches last accepted nonce (replay) | No |
0x0505 | ErrorMigrationRateLimitExceeded | Too many migrations within time window (DoS protection) | No |
0x0506 | ErrorMigrationInProgress | Migration already in progress, frame rejected | No |
Control Frame Errors (0x0600 - 0x06FF)
| Code | Name | Description | Fatal |
|---|
0x0600 | ErrorInvalidControlFrame | Malformed control frame | No |
0x0601 | ErrorUnknownControlType | Unknown control frame type | No |
Generic Errors (0xFF00 - 0xFFFF)
| Code | Name | Description | Fatal |
|---|
0xFF00 | ErrorInternalError | Internal protocol implementation error | Yes |
0xFF01 | ErrorResourceExhausted | Server resources exhausted (memory, connections) | No |