Error Catalogue

Error Catalogue

← Home

Every variant of VoiceError, what triggers it, and how a caller should handle it.

The assembler returns errors via AssemblyEvent::Rejected(VoiceError); the builder returns them as Result<EncodedMessage, VoiceError>.

---

Header / structure errors (parse time)

Variant	Trigger	Handle
TooShort { len, needed }	Frame shorter than HEADER_SIZE = 16 B.	Drop. Probably a non-voice packet.
TooLarge { len, max }	Frame larger than MAX_PACKET_SIZE = 231 B.	Drop; sender is broken.
BadVersion(b)	First byte ≠ 0x03.	Drop; V2 or future protocol version.
ReservedFlagSet(b)	Any reserved bit of type_flags is set (mask 0x2F).	Drop; V2 frame or sender bug.
ReservedPacketType	packet_type == 3.	Drop; reserved.
ZeroMessageId	message_id == 0.	Drop; spec forbids zero.
BadTotal(0)	total_data == 0.	Drop; spec forbids.
TooMuchParity(n)	parity_count > 128.	Drop; FEC coder limit.
BadIndex { idx, total }	chunk_index ≥ total_data (DATA) or ≥ parity_count (PARITY).	Drop.
ParityCountDecrease { first, got }	A later frame's parity_count is less than the value the first frame established (it MAY grow on retransmit, MUST NOT shrink).	Drop.

Body / chunk-size errors

Variant	Trigger	Handle
ChunkTooSmall(n)	Builder: chunk_size < MIN_CHUNK_SIZE.	Sender bug.
ChunkTooLarge { got, max }	Body length out of MIN_CHUNK_SIZE..=MAX_BODY_SIZE (assembler) or oversized chunk_size (builder).	Drop / sender bug.
BodyLenMismatch { got, expected }	DATA / PARITY body length differs from established chunk_size (excluding final DATA, which may be shorter).	Drop.
AudioTooLarge { bytes, max }	Builder: input audio exceeds MAX_CHUNKS_PER_MESSAGE × chunk_size.	Sender splits or compresses.

Codec / template errors

Variant	Trigger	Handle
UnknownCodec(b)	Codec byte is unassigned (not 0..=3).	Drop; surface "codec unsupported".
UnsupportedCodec(codec)	Codec is known but not in this receiver's supported_codecs set (e.g. an Opus-only build hearing AMR-NB). Rejected before any reassembly state is allocated.	Drop; surface "codec unsupported".
CodecMismatch { first, got }	Frame's codec ≠ first frame's codec.	Drop; counts a validation strike.
TotalMismatch { first, got }	Frame's total_data ≠ first frame's total_data.	Drop; counts a validation strike.
StreamSeqMismatch { first, got }	Frame's stream_seq ≠ first frame's stream_seq.	Drop; counts a validation strike.

After MAX_VALIDATION_STRIKES = 3 such mismatches on the same in-progress entry, the entry is evicted and blacklisted to free its per-sender slot.

Integrity errors

Variant	Trigger	Handle
BadMac	Header SHA-256 integrity tag mismatch (corruption or PSK-holder tampering).	Drop silently.

NACK errors

Variant	Trigger	Handle
NackTooShort	NACK body shorter than 2 + ⌈total_data/8⌉ bytes.	Drop.
BadNackIndex(n)	A NACK frame's chunk_index is non-zero (spec §3.4 requires 0).	Drop.

FEC errors

Variant	Trigger	Handle
Fec(s)	The Reed-Solomon coder returned an internal error.	Sender bug or memory issue.

Resource bounds

Variant	Trigger	Handle
Blacklisted	(from, message_id) is on the recently-completed blacklist.	Drop; expected for late late frames.
PerSenderCap(from)	New message_id from a sender already at MAX_IN_PROGRESS_PER_SENDER (= 4).	Drop; rate-limit signal.

Builder errors (send time)

These are returned by build_message / VoiceSender::send, not by the assembler, so they affect the local sender rather than an inbound frame.

Variant	Trigger	Handle
Rng(s)	The OS random-number generator was unavailable while allocating a message_id.	Fail the send; retry later. Should never happen on a healthy host.

---

Severity guide for receivers

• Silent drop, expected: Blacklisted, Duplicate (returned as the AssemblyEvent, not an error), BadVersion, ReservedPacketType.
• Silent drop, log at debug: any structural / template / chunk-size error.
• Log at warn: BadMac, PerSenderCap — signs of corruption or rate-limit pressure.
• Surface to UI / app: UnknownCodec and UnsupportedCodec (the user may want to install or enable a codec); Rng (a failed send the user should be told about).

→ Continue to Glossary.