ratelimit/local_ratelimit: emit `Retry-After` header dynamically on 429 responses
#45,384 opened on Jun 2, 2026
Repository metrics
- Stars
- (27,997 stars)
- PR merge metrics
- (Avg merge 8d) (378 merged PRs in 30d)
Description
Description:
When either the global (envoy.filters.http.ratelimit) or local (envoy.filters.http.local_ratelimit) rate limit filter enforces a limit, it emits a 429 and optionally the IETF draft-03 header triple (x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset) if enable_x_ratelimit_headers: DRAFT_VERSION_03 is configured. However, neither filter emits Retry-After on 429 responses.
Retry-After on 429 is specified by RFC 6585 section 4, with the field format defined by RFC 9110 section 10.2.3 as an HTTP-date or delay-seconds integer. Both filter paths already compute the reset value needed to populate it. Only the emission is missing.
The existing response_headers_to_add field on both filter protos does not satisfy this: it accepts only static values and cannot express a value derived dynamically from rate limit state at request time.
Desired behaviour: add an opt-in flag to both filter protos — mirroring enable_x_ratelimit_headers — that causes the filter to emit Retry-After: <delay-seconds> on 429 responses only, with the value sourced dynamically from the most-restrictive matched rule's seconds-until-reset, clamped to ≥1.
Relevant Links:
- RFC 9110 section 10.2.3 (
Retry-After): https://www.rfc-editor.org/rfc/rfc9110#section-10.2.3 - RFC 6585 section 4 (429 with
Retry-After): https://www.rfc-editor.org/rfc/rfc6585#section-4 - Related dormant issue (custom response headers, 2018): https://github.com/envoyproxy/envoy/issues/3555
- Related dormant issue (
x-ratelimit-*headers proposal, 2021): https://github.com/envoyproxy/envoy/issues/12356 - Envoy Gateway feature request that prompted this upstream ask: https://github.com/envoyproxy/gateway/issues/9078