8. 错误处理 (Error Handling)

当流无法成功完成时, QUIC 允许应用突然终止 (重置) 该流并传达原因; 参见 [QUIC-TRANSPORT] 的第 2.4 节。这称为 "流错误 (stream error)"。HTTP/3 实现可以决定关闭 QUIC 流并传达错误类型。第 8.1 节定义了错误码的线路编码。流错误不同于指示错误条件的 HTTP 状态码。流错误表示发送方未传输或消费完整的请求或响应, 而 HTTP 状态码表示成功接收的请求的结果。

如果需要终止整个连接, QUIC 同样提供了传达原因的机制; 参见 [QUIC-TRANSPORT] 的第 5.3 节。这称为 "连接错误 (connection error)"。与流错误类似, HTTP/3 实现可以终止 QUIC 连接并使用第 8.1 节中的错误码传达原因。

尽管关闭流和连接的原因称为 "错误", 但这些操作不一定表示连接或任一实现存在问题。例如, 如果不再需要请求的资源, 可以重置流。

端点可以在某些情况下选择将流错误视为连接错误, 以响应单个流上的条件关闭整个连接。实现在做出此选择之前需要考虑对未完成请求的影响。

由于可以在不进行协商的情况下定义新的错误码 (参见第 9 节), 因此在意外上下文中使用错误码或接收未知错误码必须被视为等同于 H3_NO_ERROR。但是, 无论错误码如何, 关闭流都可能产生其他影响; 例如, 参见第 4.1 节。

8.1. HTTP/3 错误码 (HTTP/3 Error Codes)

定义了以下错误码用于突然终止流、中止读取流或立即关闭 HTTP/3 连接。

H3_NO_ERROR (0x0100)
无错误。当需要关闭连接或流但没有错误要发出信号时使用。

H3_GENERAL_PROTOCOL_ERROR (0x0101)
对等方违反了协议要求, 其方式不匹配更具体的错误码, 或者端点拒绝使用更具体的错误码。

H3_INTERNAL_ERROR (0x0102)
HTTP 栈中发生了内部错误。

H3_STREAM_CREATION_ERROR (0x0103)
端点检测到其对等方创建了它不会接受的流。

H3_CLOSED_CRITICAL_STREAM (0x0104)
HTTP/3 连接所需的流被关闭或重置。

H3_FRAME_UNEXPECTED (0x0105)
接收到在当前状态或当前流上不允许的帧。

H3_FRAME_ERROR (0x0106)
接收到无法满足布局要求或大小无效的帧。

H3_EXCESSIVE_LOAD (0x0107)
端点检测到其对等方表现出可能产生过度负载的行为。

H3_ID_ERROR (0x0108)
流 ID 或推送 ID 使用不正确, 例如超过限制、减少限制或重用。

H3_SETTINGS_ERROR (0x0109)
端点在 SETTINGS 帧的有效负载中检测到错误。

H3_MISSING_SETTINGS (0x010a)
在控制流的开头未接收到 SETTINGS 帧。

H3_REQUEST_REJECTED (0x010b)
服务器在不执行任何应用处理的情况下拒绝了请求。

H3_REQUEST_CANCELLED (0x010c)
请求或其响应 (包括推送的响应) 被取消。

H3_REQUEST_INCOMPLETE (0x010d)
客户端的流在不包含完整形式的请求的情况下终止。

H3_MESSAGE_ERROR (0x010e)
HTTP 消息格式错误, 无法处理。

H3_CONNECT_ERROR (0x010f)
响应 CONNECT 请求建立的 TCP 连接被重置或异常关闭。

H3_VERSION_FALLBACK (0x0110)
请求的操作无法通过 HTTP/3 提供服务。对等方应当通过 HTTP/1.1 重试。

格式为 0x1f * N + 0x21 (对于非负整数值 N) 的错误码被保留, 以行使将未知错误码视为等同于 H3_NO_ERROR 的要求 (第 9 节)。实现应当在本应发送 H3_NO_ERROR 时以某种概率从此空间中选择错误码。