Early Review of draft-ietf-httpapi-ratelimit-headers-10
review-ietf-httpapi-ratelimit-headers-10-httpdir-early-pardue-2026-01-16-00

The document defines RateLimit header fields for HTTP that augment the extant
Retry-After field and fill several capability gaps that affect concrete HTTP
use cases.

I am not a rate-limiting expert but the technical design presented seems sound.
The range of examples presented in appendix B suggest that several aspects have
been thoughtfully considered, especially with respect to slotting this in to
the current ecosystem.

However, I'm marking this document as not ready. Primarily this is because of
the number of minor-ish things I noticed during the review, that add up to a
document that seems to lack some precision of the core protocol elements, while
containing some bloat that distracts. I believe a strong editorial pass through
the document would improve the ability for new implementers to more easily pick
this document and run with it.

Below are a detailed set of notes captured during a single front-to-back
review. As always, these comments are made as suggestions and I do not expect
everyone of them to be actioned, especially if the authors have a suitable
response. However, I think the parameter extensibility is the largest concern
that does significant work in order to switch my review position.

# Abstract

1. "thereby allowing clients to avoid being throttled"
  - I didn't understand this on first inspection and after having read the
  whole document I am still unclear. Are clients throttling themselves or
  trying to avoid being throttled. The usage of the term seems a bit loose.

# Section 1
2. "Rate limiting of HTTP clients has become a widespread practice, especially
for HTTP APIs. "
  - has become, or is?
  - is the reference to HTTP APIs important and justification for the
  "especially" qualifier? Nothing elsewhere in the document seemed to imply
  that. - what is rate limiting - cite HTTP at the earliest convenience,
  currently its later on in the document

3. "Typically, servers who do so so limit the number of acceptable"
 - This sentence seems clunky

4. "See Appendix A for further information on the current usage"
  - what is usage here?
  - about half the text in appendix A seems like it could be cut, especially
  interoperability issues.

5. "Currently, there is no standard way to communicate quotas"
  - at this stage its not super clear what is quota. You could probably just
  move some of the useful text from appendix A into the introduction to address
  that. - can probably drop the currently no standard bit, there will be once
  this draft is published

6. "RateLimit-Policy: a quota policy, defined by the server, that client HTTP
requests will consume."
  - what does "requests will consume" mean here? Its a Passive voice. Consider
  rewording such as "RateLimit-Policy: a quota policy defined by the server.
  Client requests consume quota.

7. "RateLimit: the currently remaining quota available for a specific policy."
  - "currently" is ambiguous, would be clearer to be more specific e.g. "the
  remaining quota for a specific policy at the moment the response is
  generated" or whatever is technical correct for this doc

8. "These fields enable establishing complex rate limiting policies"
  - what is being established exactly? A server can make up a policy however it
  likes. It seems the intent is more about communicating and working with
  policies?

# Section 1.1

9. The section is named "Goals" but it includes a mix of things.

"interoperabilty"
 - seems superfluous, this is the goal of internet standards. Suggest dropping
 it.

"resiliency"
 - ok

"documentation"
 - never mentioned again

Suggest you fold this section into the introduction by dropping the 2
distracting goals. The resiliency angle follows on nicely from the last
sentence of section 1.

# Section 1.2

10. * Why is Origin imported from [WEB-ORIGIN] not [HTTP]?

11. [SF] is not consistent with reference style, use [STRUCTURED-FIELDS] -
https://httpwg.org/admin/editors/style-guide#reference-style

# Section 2

12. Why have a terminology section when we already have a notational convention
section? Perhaps rename 1.12 as Terms and Definitions and put it all in one
place

13. What is a "resource server"? Probably want to change this to "server" or
something otherwise aligned with HTTP terminology.

14. "Quota policies can be advertised by servers, but they are not required to
be, and more than one quota policy can affect a given request from a client to
a server."

This is a bit of a long sentence with some awkward grammar. Suggest splitting
into shorter sentences and rewriting "but are not required to be" to be
clearer. "Request from a client to a server" is a superfluous statement.

15. List and Item are defined and they don't need to be because they are
already imported

# Section 3

16. The "RateLimit-Policy" response header field is a non-empty List[SF] of
Quota Policy Items (Section 3.1). The Item[SF] value MUST be a String[SF].

 - There seems to be a stress on non-empty but I'm unsure what this is supposed
 to represent. Stuctured fields states "An empty List is denoted by not
 serializing the field at all. This implies that fields defined as Lists have a
 default empty value.". So absence of the field can be interpreted as an empty
 List. There doesn't seem to be a clear statement about this "non-empty"
 condition so is it really important?

 - You might want to reword this sentence to "The "RateLimit-Policy" response
 header field is a List of Strings. Each list item identifies a Quota Policy
 (Section 3.1).", which would make it more compliant with
 https://httpwg.org/admin/editors/style-guide#structured-fields

- The text in paragraph 2 should be reordered/restructured. Explain simply and
clearly what the field is used for first. Requirements about its usage and
relationship to other headers are secondary. The use of the normative MAY here,
in reference to a different header, is confusing.

17. The field value SHOULD remain consistent over a sequence of HTTP responses.

- This is a weak requirement. Who does it apply to? Is it on servers to send a
consistent value (and if so, when does it make sense not to). It it on clients
to detect inconsistencies, and if so what should they do? Under what
circumstances might they be inconsistent but its not a problem?

18. Lists of Quota Policy Items (Section 3.1) can be split over multiple
"RateLimit-Policy" fields in the same HTTP response as described in Section 3.1
of [SF].

 - This is a hard to read statement that seems to have a minor technical
 problem. Why is it important to say this. The wording here - "same HTTP
 response" is in conflict with Section 3.1 of Structured Fields, which says
 "Lists can have their members split across multiple lines of the same header
 or trailer section". Restating things risks interoperability errors and
 affects long-term maintenance of protocol documents.

 - The example is immediately after the statement about splitting but does not
 demonstrate splitting, which is confusing. Suggest you put the example
 directly after the definitin of RateLimit-Policy field

# Section 3.1

19. "A quota policy Item contains an identifier for the policy and a set of
Parameters[SF] that contain information about a server's capacity allocation
for the policy."

 - If applying suggestions above, you could rephrase this to something like "A
 Quota Policy is identified by a String, a set of Parameters describe mandatory
 and optional details of the
policy."

- In the list of defined parameters, please add forward references to the full
definition, so that its a bit clearer the list is a summary.

20. "Other parameters are allowed and can be regarded as comments."

 - This seems dangerously permissive. Are you (un)intentionally shutting the
 door on potential extensibility? What is the use case for "comments"? If you
 have a concree use case, define a single optional parameter e.g. a `desc`
 field that is a String. Then think about whether it is human readable or not
 (i.e., whether you need language/locale etc). If you don't actually need that
 capability, state something along the lines that unknown extensions are ignored

21. "Implementation- or service-specific parameters SHOULD be prefixed
parameters with a vendor identifier, e.g. acme-policy, acme-burst."

 - Oh, there we go, now we're saying that other parameters are expected. But by
 the above definition they are all comments?

- This text indicates you need to do more work on the extensibiliy of
parameters. There's a risk people will make a landgrab for parameters and burn
the interop space. E.g. 1-character names are very appealing. It seems you'd
benefit from an IANA registry and more policy (pun intended) about use of
parameters. I suggest taking a look at
https://www.rfc-editor.org/rfc/rfc9218.html#section-4.3 for some inspiration.

22. "This field MUST NOT appear in a trailer section."

- This section is not about the RateLimit-Policy, so the requirement is in the
wrong place. - Why can't the field appear in trailers? What should a client do
if it sees one there? - That leads me on to wondering if there is a use case
for sending RateLimit headers in 1xx responses? Not sure you need to say
anything but maybe there's something here you didn't think about.

23. What is the expected behaviour for a client that receives a
RateLimit-Policy header that does not fulfill all of the requirements? E.g. if
a parameter has an invalid value

# Section 3.2

24. Are these examples really useful? There's already an example next to the
definition. Strongly suggest deleting it because it just list things that
anyone can work out for themselves.

25. This field MAY convey the time window associated with the quota, as shown
in this example:

- The section is called examples but this is a normative requirement text.

# Section 4

26. The style of definition is not entirely consistent with RateLimit-Policy,
which is a little jaring. Whatever you choose to do to address my feedback in
Section 3, it would be very beneficial to carry over here too.

# Section 4.1

27. Same observations here as in 3.1.

# Section 4.1.1

28. There is a reference to self.

# Section 4.2

29. Again the examples don't seem particularly useful. In fact, I found the
last two examples confusing when they change the units, presumably because the
hypothetical RateLimit-Policy tat the example applies to uses different units.
That is not abundantly clear. Again, suggest deleting the section.

# Section 5

30. This is the first mention that the document defines problem types! The
abstract and introduction would benefit from a short foreshadowing.

31. Since the use of problem types is optional, it might be more logical to
push this section down behind your current sections 6 and 7. I.e., define the
header fields then move onto how they are expected to be used

# Section 6

32. "Servers should be careful when returning RateLimit header fields in
redirection responses"

- Given the scary language in this sentence, should this be a "SHOULD"

33. "A service using RateLimit header fields MUST NOT convey values exposing an
unwanted volume of requests and SHOULD implement mechanisms to cap the ratio
between the remaining and the reset parameter values (see Section 8.5); this is
especially important when a quota policy uses a large time window."

- It's not clear to me what a "service" is in this context. However, more
importantly it seems like this is an unenforcable MUST NOT? The rest of the
text seems useful to describing the potential issues and providing some
recommendations but the use of MUST NOT seems like a lazy way of describing
some of the risks.

34. "Under certain conditions, a server MAY artificially lower RateLimit header
field values between subsequent requests."

- I think I understand what you're trying to say but if I was to artificially
lower the 't' parameter, wouldn't that allow a client to make more requests and
increase load? Suggest you tighten up the text here.

# Section 6.1

35. "The server SHOULD document how the partition key is generated so that
clients can predict the key value for a future request and determine if there
is sufficient quota remaining to execute the request."

- I know we're in a new era of AI but I don't think the server will be
documenting anything. Maybe the operator? I honestly have no clue what this
normative requirement is trying to do. Earlier in the draft one of the goals is
stated as eliminating the need for detailed API documentation. How would a
client access the documentation recommended in this sentence? If there is no
protocol for that, its not clear to me why it belongs in this draft.

- Its unclear to me if partition keys are opaque byte sequences or is there
supposed to be some aspect of client interop going on. Should the value be
encrypted? There's some text in the security considerations but its not super
clear to me. I tried to skip ahead to section 7.1 (consuming partition keys)
but it didn't help much.

- The above points indicate to me that the partition keys are perhaps a
sub-protocol running over the RateLimit headers and that it might help to
extact all of the taxt around partition keys into a separate section that
combines client and server considerations.

# Section 7.2

36. "An intermediary MAY alter the RateLimit header fields in such a way as to
communicate a more restrictive quota policy when:"

- This seems perhaps overly prescriptive? If I offer an intermediary service
that scales better than the origin and does request collapsing, then why can't
advertise a more permissive rate limit? You're already alluding to an
intermediary being "aware of the quota unit semantic used by the Origin Server"
so potentially that awareness allows it to make various appropiate decisions.

# Appendix A

37. As noted above, it seems some of the useful text could be migrated to the
main part of the document, while this appendix section is dropped entirely.