Error Handling
Error Handling
Error codes, graceful shutdown, and GoAway
Errors in KSP are classified by scope: Connection-Level (which compromises the entire session) and Stream-Level (which only terminates a specific stream).
Error Frame Structure
Error messages are serialized as binary packets using Type = 0xFF:
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Error Code (4 bytes) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Additional Data Length (2 bytes) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Additional Data (UTF-8, Variable) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Common Error Codes
| Code | Name | Type | Description |
|---|---|---|---|
| 0x01 | PROTOCOL_ERROR | Connection | Generic protocol violation, invalid header flag. |
| 0x03 | FLOW_CONTROL_ERROR | Connection/Stream | Endpoint sent data violating window boundaries. |
| 0x05 | FRAME_SIZE_ERROR | Connection | Packet length field exceeded server limitations. |
| 0x08 | VERSION_MISMATCH | Connection | No mutually supported protocol versions found. |
Graceful Shutdown via GoAway
To safely close a connection, an initiator sends a GoAway frame containing the ID of the last stream it processed. Both sides stop creating new streams but continue processing packets for open streams until their queue is clear.