跳到主要内容

2.3. 代理错误类型与 2.4. 定义新类型

2.3. 代理错误类型 (Proxy Error Types)​

本节列出本文档定义的代理错误类型. 此列表中的每个条目可以包含以下字段:

  • Name: 错误类型的注册名称.
  • Description: 错误类型的定义.
  • Extra Parameters: 可与该错误类型一起使用的零个或多个额外参数.
  • Recommended HTTP Status Code: 最适合此错误的 HTTP 状态码.
  • Response Only Generated by Intermediaries: 该错误是否只能出现在中介生成的响应中 (true), 或者也可能出现在正在转发的响应中 (false).
  • Reference: 本文档.

2.3.1. DNS Timeout​

Name: dns_timeout

Description: 中介在尝试为下一跳主机名查找 IP 地址时遇到超时.

Extra Parameters: None

Recommended HTTP Status Code: 504

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.2. DNS Error​

Name: dns_error

Description: 中介在尝试为下一跳主机名查找 IP 地址时遇到 DNS 错误.

Extra Parameters:

  • rcode: String, 传达指示错误类型的 DNS RCODE. 参见 [RFC8499] 第 3 节.
  • info-code: Integer, 传达指示错误类型的扩展 DNS 错误代码 [RFC8914].
  • ttl: Integer, 指示解析使用的 DNS TTL, 单位为秒.

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.3. Destination Not Found​

Name: destination_not_found

Description: 中介无法确定此请求应使用的适当下一跳; 例如, 它可能未配置. 注意, 此错误特定于网关, 网关通常需要特定配置来标识 "backend" 服务器; 当正向代理无法使用请求中的信息定位下一跳时, 使用 in-flight_request_error.

Extra Parameters: None

Recommended HTTP Status Code: 500

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.4. Destination Unavailable​

Name: destination_unavailable

Description: 中介认为下一跳不可用; 例如, 最近与其通信的尝试可能失败, 或健康检查可能表明其已宕机.

Extra Parameters: None

Recommended HTTP Status Code: 503

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.5. Destination IP Prohibited​

Name: destination_ip_prohibited

Description: 中介被配置为禁止连接到下一跳 IP 地址.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.6. Destination IP Unroutable​

Name: destination_ip_unroutable

Description: 中介找不到到下一跳 IP 地址的路由.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.7. Connection Refused​

Name: connection_refused

Description: 中介到下一跳的连接被拒绝.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.8. Connection Terminated​

Name: connection_terminated

Description: 中介到下一跳的连接在收到响应的任何部分之前关闭.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.9. Connection Timeout​

Name: connection_timeout

Description: 中介尝试打开到下一跳的连接时超时.

Extra Parameters: None

Recommended HTTP Status Code: 504

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.10. Connection Read Timeout​

Name: connection_read_timeout

Description: 中介预期在连接上收到数据 (例如响应的一部分), 但在配置的时间限制内没有收到任何新数据.

Extra Parameters: None

Recommended HTTP Status Code: 504

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.11. Connection Write Timeout​

Name: connection_write_timeout

Description: 中介尝试向连接写入数据但未能完成, 例如因为其缓冲区已满.

Extra Parameters: None

Recommended HTTP Status Code: 504

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.12. Connection Limit Reached​

Name: connection_limit_reached

Description: 中介被配置为限制它到下一跳的连接数量, 且该限制已经被超过.

Extra Parameters: None

Recommended HTTP Status Code: 503

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.13. TLS Protocol Error​

Name: tls_protocol_error

Description: 中介在与下一跳通信时遇到 TLS 错误, 可能发生在握手期间或握手之后.

Extra Parameters:

  • alert-message: Token, 表示 TLS alert 消息 [TLS] 第 6 节中适用的 description 子字段; 例如 "handshake_failure" 或 "certificate_expired".

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.14. TLS Certificate Error​

Name: tls_certificate_error

Description: 中介在验证下一跳出示的证书时遇到错误.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.15. TLS Alert Received​

Name: tls_alert_received

Description: 中介从下一跳收到 TLS alert.

Extra Parameters:

  • alert-id: Integer, 包含 TLS alert 消息 [TLS] 第 6 节中的适用字段.
  • alert-message: Token, 表示 TLS alert 消息 [TLS] 第 6 节中适用的 description 子字段; 例如 "handshake_failure" 或 "certificate_expired".

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.16. HTTP Request Error​

Name: http_request_error

Description: 中介代表源服务器生成客户端 (4xx) 响应. 适用的状态码包括但不限于 400, 403, 405, 406, 408, 411, 413, 414, 415, 416, 417 和 429.

Extra Parameters: None

Recommended HTTP Status Code: 适用的 4xx 状态码

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.17. HTTP Request Denied​

Name: http_request_denied

Description: 中介基于其配置和/或策略设置拒绝 HTTP 请求. 该请求未被转发到下一跳.

Extra Parameters: None

Recommended HTTP Status Code: 400

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.18. HTTP Incomplete Response​

Name: http_response_incomplete

Description: 中介从下一跳收到不完整响应.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.19. HTTP Response Header Section Too Large​

Name: http_response_header_section_size

Description: 中介收到对请求的响应, 但认为其头部区段过大.

Extra Parameters:

  • header-section-size: Integer, 指示收到的头部大小.

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.20. HTTP Response Header Field Line Too Large​

Name: http_response_header_size

Description: 中介收到对请求的响应, 但其中包含被认为过大的头部字段行.

Extra Parameters:

  • header-name: String, 指示触发错误的头部字段名称.
  • header-size: Integer, 指示触发错误的头部字段大小.

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.21. HTTP Response Body Too Large​

Name: http_response_body_size

Description: 中介收到对请求的响应, 但认为其主体过大.

Extra Parameters:

  • body-size: Integer, 指示收到的主体大小.

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.22. HTTP Response Trailer Section Too Large​

Name: http_response_trailer_section_size

Description: 中介收到对请求的响应, 但认为其 trailer 区段过大.

Extra Parameters:

  • trailer-section-size: Integer, 指示收到的 trailer 大小.

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.23. HTTP Response Trailer Field Line Too Large​

Name: http_response_trailer_size

Description: 中介收到对请求的响应, 但其中包含被认为过大的 trailer 字段行.

Extra Parameters:

  • trailer-name: String, 指示触发错误的 trailer 字段名称.
  • trailer-size: Integer, 指示触发错误的 trailer 字段大小.

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.24. HTTP Response Transfer-Coding Error​

Name: http_response_transfer_coding

Description: 中介在解码响应的传输编码 (transfer coding) 时遇到错误.

Extra Parameters:

  • coding: Token, 包含导致错误的具体编码, 来自 "HTTP Transfer Coding Registry".

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.25. HTTP Response Content-Coding Error​

Name: http_response_content_coding

Description: 中介在解码响应的内容编码 (content coding) 时遇到错误.

Extra Parameters:

  • coding: Token, 包含导致错误的具体编码, 来自 "HTTP Content Coding Registry".

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.26. HTTP Response Timeout​

Name: http_response_timeout

Description: 中介在等待完整响应时达到了配置的时间限制.

Extra Parameters: None

Recommended HTTP Status Code: 504

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.27. HTTP Upgrade Failed​

Name: http_upgrade_failed

Description: 中介与下一跳之间协商 HTTP 版本升级的过程失败.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.28. HTTP Protocol Error​

Name: http_protocol_error

Description: 中介在与下一跳通信时遇到 HTTP 协议错误. 只有在没有定义更具体错误时才应使用此错误.

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: false

Reference: RFC 9209

2.3.29. Proxy Internal Response​

Name: proxy_internal_response

Description: 中介在未尝试连接下一跳的情况下自行生成响应.

Extra Parameters: None

Recommended HTTP Status Code: 最适合该响应的状态码

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.30. Proxy Internal Error​

Name: proxy_internal_error

Description: 中介遇到与源服务器无关的内部错误.

Extra Parameters: None

Recommended HTTP Status Code: 500

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.31. Proxy Configuration Error​

Name: proxy_configuration_error

Description: 中介遇到与自身配置有关的错误.

Extra Parameters: None

Recommended HTTP Status Code: 500

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.32. Proxy Loop Detected​

Name: proxy_loop_detected

Description: 中介尝试将请求转发给自身, 或者通过其它方式检测到循环, 例如 [RFC8586].

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.4. 定义新的代理错误类型​

可以通过在 "HTTP Proxy Error Types" 注册表中注册来定义新的代理错误类型.

注册请求按照 [RFC8126] 第 4.5 节由专家审查 (Expert Review) 评审和批准. 推荐提供规范文档, 但并非必需.

专家在评估请求时应考虑以下因素:

  • 社区反馈.
  • 该值是否定义得足够明确.
  • 通用类型优先于特定于厂商, 应用或部署的值. 如果社区无法就通用值达成一致, 类型名称应相应地更具体, 例如带有标识厂商, 应用或部署的前缀.
  • 额外参数不应与已注册的 Proxy-Status 参数冲突.

注册请求应使用以下模板:

Name: [代理错误类型名称, 类型为 Token]

Description: [生成该代理错误类型的条件说明]

Extra Parameters: [零个或多个可选参数及其允许的 Structured Type]

Recommended HTTP Status Code: [该条目的适当 HTTP 状态码]

Response Only Generated by Intermediaries: [true 或 false]

Reference: [定义该错误类型的规范; 可选]

Notes: [可选]

如果代理错误类型可能出现在并非由中介生成的响应中, 例如在从正向连接流式传输响应时检测到错误, 从而附加 Proxy-Status trailer 字段, 则 'Response only generated by intermediaries' 应为 false. 如果该代理错误类型只出现在由中介生成的响应中, 则应为 true.

有关发送注册请求的位置, 参见注册表 https://www.iana.org/assignments/http-proxy-status.

最后于 更新