Currently Envoy supports multiple retry policies, including one based on 'retriable status codes'. There is a potential use case for another type of retry policy based on response headers.

For example, the backend could be an application server that further proxies the request routed by Envoy to a number of applications that it manages. The backend then may need to communicate back to Envoy that the request needs to be retried elsewhere due to resource constraints, an underlying application failure or other kinds of conditions.

Using a response header as a retry trigger seems more natural than using a status code; the application server can reserve certain header names for this purpose, leaving all status codes available to the underlying application (the app itself may not be generally aware of its surroundings).

This new retry policy can be configured similar to other retry policy types:

retry_policy:
  retry_on: retriable-headers
  retriable_headers:
  - X-Upstream-Try-Again

In this proposal retries are triggered by header presence only; the value can be further used to diagnose the reason for retry but is generally opaque to Envoy.