Hypertext Transfer Protocol (HTTP) Proxy-Status
2021-10-22
2024-03-25
HTTP Proxy-Status Parameters
Expert Review
Mark Nottingham
New Proxy-Status parameters and proxy error types, along with changes
to existing ones, can be requested using the registry interface or
the ietf-http-wg@w3.org mailing list.
error
The error parameter's value is a Token that is a proxy error
type. When present, it indicates that the intermediary encountered
an issue when obtaining this response.
next-hop
The next-hop parameter's value is a String or Token that
identifies the intermediary or origin server selected (and used, if
contacted) to obtain this response. It might be a hostname, IP
address, or alias.
next-protocol
The next-protocol parameter's value indicates the Application-Layer
Protocol Negotiation (ALPN) protocol identifier
of the protocol used by the intermediary to connect to the next hop when obtaining
this response.
received-status
The received-status parameter's value indicates the HTTP status code
that the intermediary received from the next-hop server when
obtaining this response.
details
The details parameter's value is a String containing additional
information not captured anywhere else. This can include
implementation-specific or deployment-specific information.
next-hop-aliases
A string containing one or more DNS aliases or
canonical names used to establish a proxied connection to the next
hop.
HTTP Proxy Error Types
Expert Review
Mark Nottingham
New Proxy-Status parameters and proxy error types, along with changes
to existing ones, can be requested using the registry interface or
the ietf-http-wg@w3.org mailing list.
dns_timeout
The intermediary encountered a timeout when trying to find
an IP address for the next-hop hostname.
None
504
true
dns_error
The intermediary encountered a DNS error when trying to
find an IP address for the next-hop hostname.
- rcode: A String conveying the DNS RCODE that indicates the
error type. See , Section 3.
- info-code: An Integer conveying the Extended DNS Error Code INFO-CODE.
See .
502
true
destination_not_found
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-band information to identify the
origin server.
None
500
true
destination_unavailable
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.
None
503
true
destination_ip_prohibited
The intermediary is configured to prohibit connections to the next-hop IP address.
None
502
true
destination_ip_unroutable
The intermediary cannot find a route to the next-hop IP address.
None
502
true
connection_refused
The intermediary's connection to the next hop was refused.
None
502
true
connection_terminated
The intermediary's connection to the next hop was closed before a complete response was received.
None
502
false
connection_timeout
The intermediary's attempt to open a connection to the next hop timed out.
None
504
true
connection_read_timeout
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.
None
504
false
connection_write_timeout
The intermediary was attempting to write data to a connection but was not able to (e.g., because its buffers were
full).
None
504
false
connection_limit_reached
The intermediary is configured to limit the number of connections it has to the next hop, and that limit has been
exceeded.
None
503
true
tls_protocol_error
The intermediary encountered a TLS error when communicating with the next hop, either during the handshake or
afterwards.
None
502
false
Not appropriate when a TLS alert is received; see
tls_alert_received.
tls_certificate_error
The intermediary encountered an error when verifying the certificate presented by the next hop.
None
502
true
tls_alert_received
The intermediary received a TLS alert from the next hop.
- alert-id: An Integer containing the applicable value from
the TLS Alerts registry. See .
- alert-message: A Token or String containing the applicable
description string from the TLS Alerts registry.
See .
502
false
http_request_error
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.
- status-code: An Integer containing the generated status
code.
- status-phrase: A String containing the generated status
phrase.
The applicable 4xx status code
true
This type helps distinguish between responses generated by
intermediaries from those generated by the origin.
http_request_denied
The intermediary rejected the HTTP request based on its configuration and/or policy settings. The request wasn't
forwarded to the next hop.
None
403
true
http_response_incomplete
The intermediary received an incomplete response to the request from the next hop.
None
502
false
http_response_header_section_size
The intermediary received a response to the request whose header section was considered too large.
- header-section-size: An Integer indicating how large the received
headers were. Note that they might not be complete;
i.e., the intermediary may have discarded or refused additional
data.
502
false
http_response_header_size
The intermediary received a response to the request containing an individual header field line that was considered too
large.
- 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.
502
false
http_response_body_size
The intermediary received a response to the request whose body was considered too large.
- body-size: An Integer indicating how large the received body was.
Note that it may not have been complete; i.e., the
intermediary may have discarded or refused additional data.
502
false
http_response_trailer_section_size
The intermediary received a response to the request whose trailer section was considered too large.
- trailer-section-size: An Integer indicating how large the
received trailers were. Note that they might not be complete;
i.e., the intermediary may have discarded or refused additional
data.
502
false
http_response_trailer_size
The intermediary received a response to the request containing an individual trailer field line that was considered
too large.
- 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.
502
false
http_response_transfer_coding
The intermediary encountered an error decoding the transfer coding of the response.
- coding: A Token containing the specific coding (from the
HTTP Transfer Coding Registry) that caused the error.
502
false
http_response_content_coding
The intermediary encountered an error decoding the content coding of the response.
- coding: A Token containing the specific coding (from the
HTTP Content Coding Registry) that caused the error.
502
false
http_response_timeout
The intermediary reached a configured time limit waiting for the complete response.
None
504
false
http_upgrade_failed
The process of negotiating an upgrade of the HTTP version between the intermediary and the
next hop failed.
None
502
true
http_protocol_error
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.
None
502
false
proxy_internal_response
The intermediary generated the response itself without attempting to connect to the next hop.
None
The most appropriate status code for the response
true
proxy_internal_error
The intermediary encountered an internal error unrelated to the origin.
None
500
true
proxy_configuration_error
The intermediary encountered an error regarding its configuration.
None
500
true
proxy_loop_detected
The intermediary tried to forward the request to itself, or a loop has been detected using different means (e.g.,
).
None
502
true