Change:
clarify fields dependencies according to the discussion in the issue -
It seems that it is not required to return all these 3 fields together. However, I was wondering if certain combinations would cause confusion. For example, if a server return RateLimit-Limit, RateLimit-Remaining but not RateLimit-Reset, such as: RateLimit-Limit: 10000, 10000;w=300 RateLimit-Remaining: 900 How would clients interpret the RateLimit-Remaining field without the RateLimit-Reset?
NAME Already fixed in and are REQUIRED; is RECOMMENDED. Can you please close if that fixes?
NAME sorry for missing the previous conversation. My take is RateLimit-Limit alone can be useful for clients. It tells the complete rate - quota in a time window. And clients can control its rate based on this field. RateLimit-Reset helps align the time window between the client and the server, but I think it can be optional. As long as client spread the load evenly, it does not need to know the reset. For example, if a server return RateLimit-Limit: 10000, 10000;w=300, that is about 33.3 RPS or 2,000 requests per min(assuming the quota unit is a request), clients can adopt it and stay below the limit. However, the problem is when RateLimit-Remaining appears without RateLimit-Reset, because it is technically not a rate number due to missing time window. To summarize my opinion - RateLimit-Reset is required when RateLimit-Remaining is specified; otherwise, RateLimit-Reset is optional. Thoughts?
NAME By design, RateLimit-Limit quota-policies are OPTIONAL and not actionable. The only actionable value of RateLimit-Limit is that is the first value. Without RateLimit-Reset, you cannot identify the current time-window because quota-policy are not actionable. In the above case, the correct response is This is the reason why RateLimit-Reset is REQUIRED
Thanks for closing NAME ! Feel free to provide further feedback since it's useful to double check the specs!
NAME wdyt on ? Do you think it could better clarify that quota-policies are optional? Thx++, R
I do agree that having both limit number and policies in the same field is a bit confusing. That is the reason I thought RateLimit-Limit could be actionable, but now I get that the policy is optional. Just look at this example you provided: RateLimit-Limit: 10000, 10000;w=300 RateLimit-Reset: 300 It seems to have duplicated information. I do understand the benefit of the extensibility in the Limit field, but it could get too complex too soon for clients to consume.
The spec to define header inter-dependencies and returning policies [x] Limit -> Reset [x] Limit, Remaining, Reset Do I have to always return all headers? No Do I have to expose all headers or I can only expose a subset? Limit,Reset are REQUIRED, Remaining is OPTIONAL Do we need to add some considerations on client implementation? Already present.
clarifies that clients MUST NOT assume a server always returns fields
Comment by Erik. In https://ietf-wg-URL You state ‘A server MAY use one or more "RateLimit" response fields defined in this document to communicate its quota policies.’ but it does not clearly define how they would be used in isolation or how a client should respond to a limited set of headers (other than discussed earlier above) My feeling is RateLimit-Limit can be optional and RateLimit-Remaining and RateLimit-Reset can be used as a pair. RateLimit-Reset would only have value in isolation if sent with a 429 response code, on other responses it would be meaningless.
It could also make sense to return Reset with other status codes such as and , so I think we don't really want to mandate a specific relation other than, at most, saying that unsuccessful requests (for a broad definition of those, possibly including and at a minimum) with this field are expected to be unsuccessful until that time elapses.
After a couple of years of adoption, my experience is the following: implementations use all 3 fields. Though theoretically one could just return and , I never found an implementation doing this :heavycheckmark: implementations don't know Remaining, and just return Limit and Reset with a fixed window (eg. 1 second). We can then recommend the following: Limit, Reset: MUST Remaining: SHOULD Since https://ietf-wg-URL I now think that we shouldn't mess with status codes. NAME if this sounds reasonable to you, I can provide a PR
Yes, it sounds good, thank you!

Discussion:
3. <del> A server MAY use one or more "RateLimit" response fields defined in this document to communicate its quota policies. </del> <ins> A server uses the "RateLimit" response fields defined in this document to communicate its quota policies according to the following rules: "RateLimit-Limit" and "RateLimit-Reset" are REQUIRED; "RateLimit-Remaining" is RECOMMENDED. </ins> The returned values refers to the metrics used to evaluate if the current request respects the quota policy and MAY not apply to