RFC 9209

The Proxy-Status HTTP Response Header Field

📅 published June 2022, from ietf

okay bestie, we're doing RFC 9209 today and it's giving main character energy 💖🎀

RFC 9209: The Proxy-Status HTTP Response Header Field 🦋

  • Written by M. Nottingham (Fastly) and P. Sikora (Google) 👯
  • Category: Standards Track, so this is the real deal 💅
  • ISSN 2070-1721 🌸
  • Dated June 2022 ⭐
  • Nothing is listed as obsoleted or updated here, so no drama 🙈

Abstract

okay so this doc defines the Proxy-Status HTTP response field, which lets an intermediary spill the tea on how it handled a response, including any errors it generated ✨

Status of This Memo

This is an Internet Standards Track document. 🔥

It's a product of the Internet Engineering Task Force (IETF), which means it represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 7841 🍓

Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc9209 🧚

Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. 💜

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as in effect on the date of publication. Please read these carefully, because they describe your rights and restrictions for this document. 🙈 Code Components pulled out of this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Revised BSD License 🌈

Table of Contents

1.  Introduction
  1.1.  Notational Conventions
2.  The Proxy-Status HTTP Field
  2.1.  Proxy-Status Parameters
    2.1.1.  error
    2.1.2.  next-hop
    2.1.3.  next-protocol
    2.1.4.  received-status
    2.1.5.  details
  2.2.  Defining New Proxy-Status Parameters
  2.3.  Proxy Error Types
    2.3.1.  DNS Timeout
    2.3.2.  DNS Error
    2.3.3.  Destination Not Found
    2.3.4.  Destination Unavailable
    2.3.5.  Destination IP Prohibited
    2.3.6.  Destination IP Unroutable
    2.3.7.  Connection Refused
    2.3.8.  Connection Terminated
    2.3.9.  Connection Timeout
    2.3.10. Connection Read Timeout
    2.3.11. Connection Write Timeout
    2.3.12. Connection Limit Reached
    2.3.13. TLS Protocol Error
    2.3.14. TLS Certificate Error
    2.3.15. TLS Alert Received
    2.3.16. HTTP Request Error
    2.3.17. HTTP Request Denied
    2.3.18. HTTP Incomplete Response
    2.3.19. HTTP Response Header Section Too Large
    2.3.20. HTTP Response Header Field Line Too Large
    2.3.21. HTTP Response Body Too Large
    2.3.22. HTTP Response Trailer Section Too Large
    2.3.23. HTTP Response Trailer Field Line Too Large
    2.3.24. HTTP Response Transfer-Coding Error
    2.3.25. HTTP Response Content-Coding Error
    2.3.26. HTTP Response Timeout
    2.3.27. HTTP Upgrade Failed
    2.3.28. HTTP Protocol Error
    2.3.29. Proxy Internal Response
    2.3.30. Proxy Internal Error
    2.3.31. Proxy Configuration Error
    2.3.32. Proxy Loop Detected
  2.4.  Defining New Proxy Error Types
3.  IANA Considerations
4.  Security Considerations
5.  References
  5.1.  Normative References
  5.2.  Informative References
Authors' Addresses

1. Introduction

okay so HTTP intermediaries (see Section 3.7 of [HTTP]) are a huge deal now, including forward proxies and gateways (also known as "reverse proxies") 💅 Reverse proxies and content delivery networks (CDNs) are literally part of the critical infrastructure of a lot of websites 🌐

Usually, intermediaries forward requests toward the origin server (inbound) and then forward the responses back to clients (outbound). But if something goes wrong before an inbound server gives back a response, the intermediary is often the one that generates the response itself 💀

HTTP has a few status codes for these situations, like 502 (Bad Gateway) and 504 (Gateway Timeout). Still, experience has shown that people need more info to debug things and to understand what happened from the client's side 🙈 Intermediaries also sometimes want to share extra details about how they handled a response, even when they didn't generate it themselves ✨

To make all of that possible, Section 2 defines a new HTTP response field so intermediaries can share details about how they handled a response. Section 2.1 lists the info an intermediary can add to the field, and that list can be extended per Section 2.2. Section 2.3 defines a set of error types for when a proxy runs into trouble getting a response for the request, and those can also be extended per Section 2.4 🦋

1.1. Notational Conventions

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 🫶

This doc uses the following terminology from Section 3 of [STRUCTURED-FIELDS] to specify syntax and parsing: List, String, Token, Integer, and Byte Sequence 🧚

One thing to note: in this spec, "proxy" means both forward and reverse proxies, which are also called gateways. "Next hop" means the connection in the direction that leads to the origin server for the request 🍓

2. The Proxy-Status HTTP Field ✨

The Proxy-Status HTTP response field lets an intermediary share extra info about how it handled a response and its associated request 💖

Its value is a List (see Section 3.1 of [STRUCTURED-FIELDS]). Each member of the List represents an intermediary that handled the response. The first member is the intermediary closest to the origin server, and the last member is the intermediary closest to the user agent 👑

For example:

Proxy-Status: revproxy1.example.net, ExampleCDN

This says the response was handled first by revproxy1.example.net (a reverse proxy right next to the origin server) and then by ExampleCDN 🎀

Intermediaries decide when it makes sense to add the Proxy-Status field to a response. Some might add it to every response, while others might only do it when they're specifically configured to, or when the request has a header field that turns on a debugging mode 🔥

each member of the List identifies the intermediary that inserted the value and MUST have a type of either String or Token. This might be a service name (but not a software or hardware product name; "ExampleCDN" is appropriate, but "ExampleProxy" is not because it doesn't identify the deployment 🙈), a hostname ("proxy-3.example.com"), an IP address, or a generated string 🌸

Parameters of each member (per Section 3.1.2 of [STRUCTURED-FIELDS]) carry extra info about that intermediary's handling of the response and its associated request. See Section 2.1 for those. While all of these parameters are OPTIONAL, intermediaries are encouraged to provide as much info as possible (but see Section 4 for security considerations in doing so) 💅

when an intermediary adds a value to the Proxy-Status field, it SHOULD preserve the existing members of the field so the whole chain of intermediaries handling the request can be debugged, unless it's explicitly configured to remove them (for example, to keep internal network details from leaking; see Section 4) 🧚

origin servers MUST NOT generate the Proxy-Status field. 🚫

Proxy-Status MAY be sent as an HTTP trailer field. For example, say an intermediary is streaming a response and the inbound connection suddenly terminates. Proxy-Status can then only be appended to the trailer section of the outbound message, since the header section has already been sent 😭 However, trailer fields might get silently discarded along the path to the user agent (that's true for all trailer fields; see Section 6.5 of [HTTP]), so Proxy-Status SHOULD NOT be sent as a trailer field unless it's not possible to send it in the header section 💀

so that recipients can rebuild the relative order of Proxy-Status members sent in trailer fields alongside those sent in header fields, an intermediary MUST NOT send Proxy-Status as a trailer field unless it has also generated a Proxy-Status header field with the same member (although the parameters might be different) in that message. 🦋

Here's an example. A proxy named 'ThisProxy' gets a response that already has this header field:

Proxy-Status: SomeOtherProxy

It adds its own entry to the header field:

Proxy-Status: SomeOtherProxy, ThisProxy

That lets it append this trailer field:

Proxy-Status: ThisProxy; error=read_timeout

Now a downstream recipient can tell that processing by 'SomeOtherProxy' happened before 'ThisProxy' 🧚

a client MAY promote the Proxy-Status trailer field into a header field by following these steps: 🌈

  1. For each member trailer_member of the Proxy-Status trailer field value:
    1. Let header_member be the first (leftmost) value of the Proxy-Status header field value, comparing the String or Token character by character without considering parameters.
    2. If no matching header_member is found, continue processing the next trailer_member.
    3. Replace header_member with trailer_member in its entirety, including any parameters.
  2. Remove the Proxy-Status trailer field if it's empty.

2.1. Proxy-Status Parameters

This section lists the parameters that can be used on members of the Proxy-Status field. Unrecognised parameters MUST be ignored. 💜

2.1.1. error 💖

okay so the error parameter's value is a Token that names a proxy error type 🦋. when it's there, it means the intermediary hit a snag while getting this response.

some proxy error types mean the intermediary made the response itself, not that it got forwarded from the origin. like if the origin server can't be contacted, the proxy has to whip up its own response 🧚

other types can get tacked onto responses that the origin or some other inbound server made, even partial ones. for example, if the forward connection suddenly closes, an intermediary might add Proxy-Status with a fitting error as a trailer field 😭

types registered with 'Response only generated by intermediaries' set to 'true' can only show up in responses the intermediary generated. if it's 'false', the response might have come from the intermediary or from an inbound server 🌸

Section 2.3 has the proxy error types this document defines, and if you want to make a new one, Section 2.4 walks you through the procedure ✨

here's a sweet example:

HTTP/1.1 504 Gateway Timeout
Proxy-Status: ExampleCDN; error=connection_timeout

this one says the 504 was generated by ExampleCDN because the connection timed out when going forward 💅

and another one:

HTTP/1.1 429 Too Many Requests
Proxy-Status: r34.example.net; error=http_request_error, ExampleCDN

this 429 (Too Many Requests) was generated by r34.example.net, not the CDN or the origin 👑

when you're sending the error parameter, the most specific proxy error type SHOULD be sent, as long as it accurately describes what went wrong 🎀 if there's no fitting type defined, there are some generic ones you can use, like proxy_internal_error or http_protocol_error. if those don't fit either, go ahead and consider registering a new proxy error type (see Section 2.4) 🫶

each proxy error type also has a recommended HTTP status code. when you generate an HTTP response with the error in it, its HTTP status code SHOULD be set to that recommended one. buuut there might be situations where a different status code gets used, like for backwards compatibility with older behaviours, or when a status code was already sent 🙈

proxy error types can also define any number of extra parameters for use with that type. using them is optional, same as all parameters. so if you use an extra parameter with a proxy error type that doesn't define it, it just gets ignored 💜

2.1.2. next-hop 🍓

the next-hop parameter's value is a String or Token that identifies the intermediary or origin server that was picked (and used, if it got contacted) to get this response. it might be a hostname, an IP address, or an alias 🌈

Proxy-Status: cdn.example.org; next-hop=backend.example.org:8001

this says cdn.example.org used backend.example.org:8001 as the next hop for this request 🦋

2.1.3. next-protocol 💜

the next-protocol parameter's value tells you the Application-Layer Protocol Negotiation (ALPN) protocol identifier [RFC7301] of the protocol the intermediary used to connect to the next hop when it got this response ✨

the value MUST be either a Token or a Byte Sequence representing a TLS ALPN Protocol ID. you can find the list over at <https://www.iana.org/assignments/tls-extensiontype-values#alpn-protocol-ids>. and if the protocol identifier can be written as a Token using ASCII encoding, that's the form that MUST be used 🔥

Proxy-Status: "proxy.example.org"; next-protocol=h2

just a heads up, the ALPN identifier is only being used here to name the protocol. it may or may not have actually been used in the negotiation 🙈

2.1.4. received-status 🌸

the received-status parameter's value is the HTTP status code the intermediary got from the next-hop server when it was getting this response 🍓

the value MUST be an Integer 💅

Proxy-Status: ExampleCDN; received-status=200

2.1.5. details 🧚

the details parameter's value is a String holding extra info that isn't captured anywhere else. this can be implementation-specific or deployment-specific stuff 🫶

Proxy-Status: proxy.example.net; error="http_protocol_error";
              details="Malformed response header: space before colon"

2.2. Defining New Proxy-Status Parameters 🦋

if you want a brand new Proxy-Status parameter, you register it in the "HTTP Proxy-Status Parameters" registry 💖

registration requests get reviewed and approved by Expert Review, per [RFC8126], Section 4.5. a specification document is appreciated but not required 🌈

when the experts are evaluating requests, they should look at these things:

  • community feedback
  • whether the value is sufficiently well defined
  • generic parameters are preferred over vendor-specific, application-specific, or deployment-specific ones. if a generic value can't be agreed on by the community, the parameter's name should be correspondingly specific (like with a prefix that identifies the vendor, application, or deployment) 👑
  • parameter names should not conflict with registered extra parameters in the "HTTP Proxy Error Types" registry

your registration request should use this template:

Name:  [a name for the Proxy-Status parameter that matches key]

Description:  [a description of the parameter semantics and value]

Reference:  [to a specification defining this parameter; optional]

for where to send your requests, check out the registry at <https://www.iana.org/assignments/http-proxy-status> 🎀

2.3. Proxy Error Types ✨

this section lists the proxy error types this document defines. for info on making new ones, see Section 2.4 🫶

heads up: implementations might not produce all of these proxy error types. the set below was designed to match states that already exist in implementations, so some of them may not apply to everyone 🌸

2.3.1. DNS Timeout ⏰

the intermediary timed out while trying to find an IP address for the next-hop hostname. it's giving "couldn't get an answer in time" 😭

Name:  dns_timeout
Extra Parameters:  None
Recommended HTTP Status Code:  504
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.2. DNS Error 🌐

the intermediary ran into a DNS error while trying to find an IP address for the next-hop hostname. this one has two 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 INFO-CODE. see [RFC8914].
Name:  dns_error
Extra Parameters:  rcode, info-code
Recommended HTTP Status Code:  502
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.3. Destination Not Found 🧭

the intermediary can't figure out which next hop to use for this request, maybe because it isn't configured. this one is mostly a gateways thing, since gateways usually need specific config to find the "backend" server. forward proxies use in-band info to find the origin server instead 🙈

Name:  destination_not_found
Extra Parameters:  None
Recommended HTTP Status Code:  500
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.4. Destination Unavailable 🚫

the intermediary thinks the next hop is unavailable. maybe recent attempts to talk to it failed, or a health check says it's down 💀

Name:  destination_unavailable
Extra Parameters:  None
Recommended HTTP Status Code:  503
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.5. Destination IP Prohibited 🛑

the intermediary is set up to block connections to the next-hop IP address. not allowed, bestie 🙅‍♀️

Name:  destination_ip_prohibited
Extra Parameters:  None
Recommended HTTP Status Code:  502
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.6. Destination IP Unroutable 🗺️

the intermediary can't find a route to the next-hop IP address. lost in the sauce 😭

Name:  destination_ip_unroutable
Extra Parameters:  None
Recommended HTTP Status Code:  502
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.7. Connection Refused 🙅

the intermediary's connection to the next hop got refused. rude 💅

Name:  connection_refused
Extra Parameters:  None
Recommended HTTP Status Code:  502
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.8. Connection Terminated 💔

the intermediary's connection to the next hop got closed before a complete response showed up. the response was cut off mid-sentence, and it's giving unfinished 😭

Name:  connection_terminated
Extra Parameters:  None
Recommended HTTP Status Code:  502
Response Only Generated by Intermediaries:  false
Reference:  RFC 9209

2.3.9. Connection Timeout ⌛

the intermediary tried to open a connection to the next hop and it timed out. waited forever and nothing 🥲

Name:  connection_timeout
Extra Parameters:  None
Recommended HTTP Status Code:  504
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.10. Connection Read Timeout 📖

the intermediary was waiting for data on a connection (like part of a response), but no new data showed up within a configured time limit. ghosted, literally 👻

Name:  connection_read_timeout
Extra Parameters:  None
Recommended HTTP Status Code:  504
Response Only Generated by Intermediaries:  false
Reference:  RFC 9209

2.3.11. Connection Write Timeout ✍️

the intermediary was trying to write data to a connection but couldn't, like when its buffers are full. it's a traffic jam in there 🚗💨

Name:  connection_write_timeout
Extra Parameters:  None
Recommended HTTP Status Code:  504
Response Only Generated by Intermediaries:  false
Reference:  RFC 9209

2.3.12. Connection Limit Reached 🚧

the intermediary has a configured limit on how many connections it can have to the next hop, and that limit got exceeded. too many friends, not enough room 🫠

Name:  connection_limit_reached
Extra Parameters:  None
Recommended HTTP Status Code:  503
Response Only Generated by Intermediaries:  true
Reference:  RFC 9209

2.3.13. TLS Protocol Error 🔐

the intermediary ran into a TLS error while talking to the next hop, either during the handshake or after it 🥀

Name:  tls_protocol_error
Extra Parameters:  None
Recommended HTTP Status Code:  502
Response Only Generated by Intermediaries:  false
Reference:  RFC 9209
Notes:  Not appropriate when a TLS alert is received; see tls_alert_received.

2.3.14. TLS Certificate Error 📜

the intermediary hit an error while verifying the certificate the next hop presented. the cert didn't pass the vibe check 🙅‍♀️💖

Name:  tls_certificate_error
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: okay so this one's for when the intermediary gets a TLS alert from the next hop 🚨 the handshake drama is coming from downstream 💅

Extra Parameters:

  • alert-id: An Integer containing the applicable value from the "TLS Alerts" registry. See [TLS].
  • alert-message: A Token or String containing the applicable description string from the "TLS Alerts" registry. See [TLS].

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: bestie, this is when the intermediary writes a client (4xx) response on the origin's behalf 🫶 the applicable status codes include (but aren't limited to) 400, 403, 405, 406, 408, 411, 413, 414, 415, 416, 417, and 429.

Extra Parameters:

  • status-code: An Integer containing the generated status code.
  • status-phrase: A String containing the generated status phrase.

Recommended HTTP Status Code: The applicable 4xx status code

Response Only Generated by Intermediaries: true

Reference: RFC 9209

Notes: this type helps you tell apart responses the intermediary made itself from the ones the origin made 🔍 very important, very iconic 👑

2.3.17. HTTP Request Denied 🚫

Name: http_request_denied

Description: the intermediary said "absolutely not" to the HTTP request based on its configuration and/or policy settings 💀 the request never got forwarded to the next hop, so no cap, it never left the building ✨

Extra Parameters: None

Recommended HTTP Status Code: 403

Response Only Generated by Intermediaries: true

Reference: RFC 9209

2.3.18. HTTP Incomplete Response 🧩

Name: http_response_incomplete

Description: the intermediary got an incomplete response to the request from the next hop 😭 half a plate of response, lowkey tragic 🍓

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 got a response whose header section was considered too large 🥴 it's giving a whole novel in the headers, periodt.

Extra Parameters:

  • 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.

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 got a response with one individual header field line that was considered too large 🙅‍♀️ one line, one problem, that's the vibe.

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 got a response whose body was considered too large 🫠 the body was simply too extra for the intermediary to handle.

Extra Parameters:

  • 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.

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 got a response whose trailer section was considered too large 😵 even the trailers came in with main character energy and it was too much.

Extra Parameters:

  • 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.

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 got a response with one individual trailer field line that was considered too large 🥲 same energy as the header line one, just at the end of the message.

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 ran into an error while decoding the transfer coding of the response 😩 the wrapping paper couldn't be unwrapped, bestie.

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 ran into an error while decoding the content coding of the response 🥺 same vibe as the transfer one, just for the content layer.

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 hit a configured time limit while waiting for the complete response ⌛ it waited, and waited, and the vibes just ran out 💔

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 😤 they tried to glow up together and it just didn't work out.

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 ran into an HTTP protocol error while talking to the next hop 🙃 this one should only be used when a more specific one isn't defined, so it's the catch-all bestie, use it as a last resort 🧺

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 made the response itself without even trying to connect to the next hop 🪄 it's a DIY situation, no backend needed.

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 ran into an internal error that's totally unrelated to the origin 😬 this one's the proxy's own drama, not the origin's fault 🙅‍♀️

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 ran into an error regarding its configuration 🫣 it's the proxy's settings having a moment, not the request's fault.

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 got detected using different means (e.g., [RFC8586]) 🌀 it's giving "I'm my own next hop" and that's not it, bestie.

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 📮

3. IANA Considerations 🗂️

IANA has created the "HTTP Proxy-Status Parameters" registry and the "HTTP Proxy Error Types" registry at <https://www.iana.org/assignments/http-proxy-status> and has populated them with the types defined in Sections 2.1 and 2.3 respectively; see Sections 2.2 and 2.4 for their associated procedures ✨

Additionally, the following entry has been added to the "Hypertext Transfer Protocol (HTTP) Field Name Registry":

Field name:  Proxy-Status
Status:  permanent
Specification document(s):  RFC 9209
Comments:

4. Security Considerations 🔐

One of the primary security concerns when using Proxy-Status is leaking information that might aid an attacker 🚨 this is serious, bestie. For example, information about the intermediary's configuration and backend topology can be exposed, allowing attackers to directly target backend services that are not prepared for high traffic volume or malformed inputs. Some information might only be suitable to reveal to authorized parties.

As a result, care needs to be taken when deciding to generate a Proxy-Status field and what information to include in it. Note that intermediaries are not required to generate a Proxy-Status field in any response and can conditionally generate them based upon request attributes (e.g., authentication tokens, IP address) 🛡️

Likewise, generation of all parameters is optional, as is the generation of the field itself. Also, the field's content is not verified; an intermediary can claim certain actions (e.g., sending a request over an encrypted channel) but fail to actually do that 🙈

5. References 📚

5.1. Normative References

Okay so these are the references the spec needs you to read, bestie. No skipping, no cap 📚💖

5.2. Informative References

These ones are good to know about but you don't have to read them to get the main idea 🦋

Authors' Addresses ✨

Meet the brains behind it all 🧠💜

Mark Nottingham
Fastly
Prahran
Australia
Email: mnot@mnot.net
URI:   https://www.mnot.net/


Piotr Sikora
Google
Email: piotrsikora@google.com
📦 where this page comes from