Skip to main content

2.3. Proxy Error Types & 2.4. Defining New Types

2.3. Proxy Error Types​

This section lists the Proxy Error Types that are defined in this document. Individual entries in this list can have the following fields:

  • Name: The registered name of the error type
  • Description: A definition of the error type
  • Extra Parameters: Zero or more extra parameters that can be used with the error type
  • Recommended HTTP Status Code: The HTTP status code that is most appropriate for this error
  • Response Only Generated by Intermediaries: Whether this error can only appear in responses generated by the intermediary (true) or might appear in responses that are being forwarded (false)
  • Reference: This document

2.3.1. DNS Timeout​

Name: dns_timeout

Description: The intermediary encountered a timeout when trying to find an IP address for the next hop hostname.

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: The intermediary encountered a DNS error when trying to find an IP address for the next hop hostname.

Extra Parameters:

  • rcode: A String conveying the DNS RCODE that indicates the error type. See [RFC8499], Section 3.
  • info-code: An Integer conveying the Extended DNS Error Code [RFC8914] that indicates the error type.
  • ttl: An Integer indicating the DNS TTL that the resolution used, in seconds.

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: The intermediary cannot determine the appropriate next hop to use for this request; for example, it may not be configured. Note that this error is specific to gateways, which typically require specific configuration to identify the "backend" server; forward proxies use in-flight_request_error when they cannot locate a next hop with the information in the request.

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: The intermediary considers the next hop to be unavailable; e.g., recent attempts to communicate with it may have failed, or a health check may indicate that it is down.

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: The intermediary is configured to prohibit connections to the next hop IP address.

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: The intermediary cannot find a route to the next hop IP address.

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: The intermediary's connection to the next hop was refused.

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: The intermediary's connection to the next hop was closed before any part of a response was received.

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: The intermediary's attempt to open a connection to the next hop timed out.

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: The intermediary was expecting data on a connection (e.g., part of a response), but did not receive any new data in a configured time limit.

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: The intermediary was attempting to write data to a connection but was not able to (e.g., because its buffers were full).

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: The intermediary is configured to limit the number of connections it has to the next hop, and that limit has been passed.

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: The intermediary encountered a TLS error when communicating with the next hop, either during the handshake or afterwards.

Extra Parameters:

  • alert-message: A Token representing the applicable description subfield of the TLS alert message [TLS], Section 6; for example, "handshake_failure" or "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: The intermediary encountered an error when verifying the certificate presented by the next hop.

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: The intermediary received a TLS alert from the next hop.

Extra Parameters:

  • alert-id: An Integer containing the applicable field of the TLS alert message [TLS], Section 6.
  • alert-message: A Token representing the applicable description subfield of the TLS alert message [TLS], Section 6; for example, "handshake_failure" or "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: The intermediary is generating a client (4xx) response on the origin's behalf. Applicable status codes include (but are not limited to) 400, 403, 405, 406, 408, 411, 413, 414, 415, 416, 417, and 429.

Extra Parameters: None

Recommended HTTP Status Code: The applicable 4xx status code

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.17. HTTP Request Denied​

Name: http_request_denied

Description: The intermediary rejected HTTP request based on its configuration and/or policy settings. The request wasn't forwarded to the next hop.

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: The intermediary received an incomplete response from the next hop.

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: The intermediary received a response to the request whose header section was considered too large.

Extra Parameters:

  • header-section-size: An Integer indicating the size of the headers received.

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: The intermediary received a response to the request containing a header field line that was considered too large.

Extra Parameters:

  • header-name: A String indicating the name of the header field that triggered the error.
  • header-size: An Integer indicating the size of the header field that triggered the error.

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: The intermediary received a response to the request whose body was considered too large.

Extra Parameters:

  • body-size: An Integer indicating the size of the body received.

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: The intermediary received a response to the request whose trailer section was considered too large.

Extra Parameters:

  • trailer-section-size: An Integer indicating the size of the trailers received.

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: The intermediary received a response to the request containing a trailer field line that was considered too large.

Extra Parameters:

  • trailer-name: A String indicating the name of the trailer field that triggered the error.
  • trailer-size: An Integer indicating the size of the trailer field that triggered the error.

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: The intermediary encountered an error decoding the transfer coding of the response.

Extra Parameters:

  • coding: A Token containing the specific coding (from the "HTTP Transfer Coding Registry") that caused the error.

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: The intermediary encountered an error decoding the content coding of the response.

Extra Parameters:

  • coding: A Token containing the specific coding (from the "HTTP Content Coding Registry") that caused the error.

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: The intermediary reached a configured time limit waiting for the complete response.

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: The process of negotiating an upgrade of the HTTP version between the intermediary and the next hop failed.

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: The intermediary encountered an HTTP protocol error when communicating with the next hop. This error should only be used when a more specific one is not defined.

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: The intermediary generated the response itself without attempting to connect to the next hop.

Extra Parameters: None

Recommended HTTP Status Code: The most appropriate status code for the response

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.30. Proxy Internal Error​

Name: proxy_internal_error

Description: The intermediary encountered an internal error unrelated to the origin.

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: The intermediary encountered an error regarding its configuration.

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: The intermediary tried to forward the request to itself, or a loop has been detected using different means (e.g., [RFC8586]).

Extra Parameters: None

Recommended HTTP Status Code: 502

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.4. Defining New Proxy Error Types​

New proxy error types can be defined by registering them in the "HTTP Proxy Error Types" registry.

Registration requests are reviewed and approved by Expert Review, per [RFC8126], Section 4.5. A specification document is appreciated but not required.

The expert(s) should consider the following factors when evaluating requests:

  • Community feedback
  • If the value is sufficiently well-defined
  • Generic types are preferred over vendor-specific, application-specific, or deployment-specific values. If a generic value cannot be agreed upon in the community, the type's name should be correspondingly specific (e.g., with a prefix that identifies the vendor, application, or deployment).
  • Extra parameters should not conflict with registered Proxy-Status parameters.

Registration requests should use the following template:

Name: [a name for the proxy error type that is of type Token]

Description: [a description of the conditions that generate the proxy error type]

Extra Parameters: [zero or more optional parameters, along with their allowable Structured Type(s)]

Recommended HTTP Status Code: [the appropriate HTTP status code for this entry]

Response Only Generated by Intermediaries: ['true' or 'false']

Reference: [to a specification defining this error type; optional]

Notes: [optional]

If the proxy error type might occur in responses that are not generated by the intermediary -- for example, when an error is detected as the response is streamed from a forward connection, causing a Proxy-Status trailer field to be appended -- the 'Response only generated by intermediaries' should be 'false'. If the proxy error type only occurs in responses that are generated by the intermediary, it should be 'true'.

See the registry at https://www.iana.org/assignments/http-proxy-status for details on where to send registration requests.

Last updated on