RateLimit Header Fields for HTTP

This document defines the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset fields for HTTP, thus allowing servers to publish current service limits and clients to shape their request policy and avoid being throttled out.¶

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.¶

This Internet-Draft will expire on November 12, 2021.¶

Copyright (c) 2021 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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶

The widespreading of HTTP as a distributed computation protocol requires an explicit way of communicating service status and usage quotas.¶

This was partially addressed by the Retry-After header field defined in [SEMANTICS] to be returned in 429 Too Many Requests (see [STATUS429]) or 503 Service Unavailable responses.¶

Still, there is not a standard way to communicate service quotas so that the client can throttle its requests and prevent 4xx or 5xx responses.¶

The following RateLimit response fields are defined¶

A server MAY use one or more RateLimit response fields defined in this document to communicate its quota policies.¶

The returned values refers to the metrics used to evaluate if the current request respects the quota policy and MAY not apply to subsequent requests.¶

Example: a successful response with the following fields¶

does not guarantee that the next request will be successful. Server metrics may be subject to other conditions like the one shown in the example from Section 2.2.¶

A server MAY return RateLimit response fields independently of the response status code. This includes throttled responses.¶

This document does not mandate any correlation between the RateLimit values and the returned status code.¶

Servers should be careful in returning RateLimit fields in redirection responses (eg. 3xx status codes) because a low RateLimit-Remaining value could limit the client from issuing requests. For example, given the rate limiting fields below, a client could decide to wait 10 seconds before following the Location header, because RateLimit-Remaining is 0.¶

If a response contains both the Retry-After and the RateLimit-Reset fields, the value of RateLimit-Reset SHOULD reference the same point in time as Retry-After.¶

When using a policy involving more than one time-window, the server MUST reply with the RateLimit fields related to the window with the lower RateLimit-Remaining values.¶

A service returning RateLimit fields MUST NOT convey values exposing an unwanted volume of requests and SHOULD implement mechanisms to cap the ratio between RateLimit-Remaining and RateLimit-Reset (see Section 9.5); this is especially important when quota-policies use a large time-window.¶

Under certain conditions, a server MAY artificially lower RateLimit field values between subsequent requests, eg. to respond to Denial of Service attacks or in case of resource saturation.¶

Servers usually establish whether the request is in-quota before creating a response, so the RateLimit field values should be already available in that moment. Nonetheless servers MAY decide to send the RateLimit fields in a trailer section.¶

This section documents the considerations advised in Section 16.3.3 of [SEMANTICS].¶

An intermediary that is not part of the originating service infrastructure and is not aware of the quota-policy semantic used by the Origin Server SHOULD NOT alter the RateLimit fields’ values in such a way as to communicate a more permissive quota-policy; this includes removing the RateLimit fields.¶

• it is aware of the quota-unit semantic used by the Origin Server;
• it implements this specification and enforces a quota-policy which is more restrictive than the one conveyed in the fields.

An intermediary SHOULD forward a request even when presuming that it might not be serviced; the service returning the RateLimit fields is the sole responsible of enforcing the communicated quota-policy, and it is always free to service incoming requests.¶

This specification does not mandate any behavior on intermediaries respect to retries, nor requires that intermediaries have any role in respecting quota-policies. For example, it is legitimate for a proxy to retransmit a request without notifying the client, and thus consuming quota-units.¶

As is the ordinary case for HTTP caching ([RFC7234]), a response with RateLimit fields might be cached and re-used for subsequent requests. A cached RateLimit response does not modify quota counters but could contain stale information. Clients interested in determining the freshness of the RateLimit fields could rely on fields such as Date and on the time-window of a quota-policy.¶

A client MUST process the received RateLimit fields.¶

A client MUST validate the values received in the RateLimit fields before using them and check if there are significant discrepancies with the expected ones. This includes a RateLimit-Reset moment too far in the future or a service-limit too high.¶

A client receiving RateLimit fields MUST NOT assume that subsequent responses contain the same RateLimit fields, or any RateLimit fields at all.¶

Malformed RateLimit fields MAY be ignored.¶

A client SHOULD NOT exceed the quota-units expressed in RateLimit-Remaining before the time-window expressed in RateLimit-Reset.¶

A client MAY still probe the server if the RateLimit-Reset is considered too high.¶

The value of RateLimit-Reset is generated at response time: a client aware of a significant network latency MAY behave accordingly and use other information (eg. the Date response header field, or otherwise gathered metrics) to better estimate the RateLimit-Reset moment intended by the server.¶

The quota-policy values and comments provided in RateLimit-Limit are informative and MAY be ignored.¶

If a response contains both the RateLimit-Reset and Retry-After fields, Retry-After MUST take precedence and RateLimit-Reset MAY be ignored.¶

• slowing down or preemptively backoff their request rate when approaching quota limits;
• consuming all the quota according to the exposed limits and then wait.

Thanks to Willi Schoenborn, Alejandro Martinez Ruiz, Alessandro Ranellucci, Amos Jeffries, Martin Thomson, Erik Wilde and Mark Nottingham for being the initial contributors of these specifications. Kudos to the first community implementors: Aapo Talvensaari, Nathan Friedly and Sanyam Dogra.¶

1. Why defining standard fields for throttling?
   
   To simplify enforcement of throttling policies.
2. Can I use RateLimit-* in throttled responses (eg with status code 429)?
   
   Yes, you can.
3. Are those specs tied to RFC 6585?
   
   No. [RFC6585] defines the 429 status code and we use it just as an example of a throttled request, that could instead use even 403 or whatever status code. The goal of this specification is to standardize the name and semantic of three ratelimit fields widely used on the internet. Stricter relations with status codes or error response payloads would impose behaviors to all the existing implementations making the adoption more complex.
4. Why don’t pass the throttling scope as a parameter?
   
   After a discussion on a similar thread we will probably add a new “RateLimit-Scope” field to this spec.
   
   I’m open to suggestions: comment on this issue
5. Why using delay-seconds instead of a UNIX Timestamp? Why not using subsecond precision?
   
   Using delay-seconds aligns with Retry-After, which is returned in similar contexts, eg on 429 responses.
   
   Timestamps require a clock synchronization protocol (see Section 5.6.7 of [SEMANTICS]). This may be problematic (eg. clock adjustment, clock skew, failure of hardcoded clock synchronization servers, IoT devices, ..). Moreover timestamps may not be monotonically increasing due to clock adjustment. See Another NTP client failure story
   
   We did not use subsecond precision because:
   • that is more subject to system clock correction like the one implemented via the adjtimex() Linux system call;
   • response-time latency may not make it worth. A brief discussion on the subject is on the httpwg ml
   • almost all rate-limit headers implementations do not use it.
6. Why not support multiple quota remaining?
   
   While this might be of some value, my experience suggests that overly-complex quota implementations results in lower effectiveness of this policy. This spec allows the client to easily focusing on RateLimit-Remaining and RateLimit-Reset.
7. Shouldn’t I limit concurrency instead of request rate?
   
   You can use this specification to limit concurrency at the HTTP level (see {#use-for-limiting-concurrency}) and help clients to shape their requests avoiding being throttled out.
   
   A problematic way to limit concurrency is connection dropping, especially when connections are multiplexed (eg. HTTP/2) because this results in unserviced client requests, which is something we want to avoid.
   
   A semantic way to limit concurrency is to return 503 + Retry-After in case of resource saturation (eg. thrashing, connection queues too long, Service Level Objectives not meet, ..). Saturation conditions can be either dynamic or static: all this is out of the scope for the current document.
8. Do a positive value of RateLimit-Remaining imply any service guarantee for my future requests to be served?
   
   No. FAQ integrated in Section 3.2.
9. Is the quota-policy definition Section 2.3 too complex?
   
   You can always return the simplest form of the 3 fields

the key value is the one referencing the lowest limit: 100 ¶

1. Can we use shorter names? Why don’t put everything in one field?

The most common syntax we found on the web is X-RateLimit-* and when starting this I-D we opted for it ¶

The basic form of those fields is easily parseable, even by implementors procesing responses using technologies like dynamic interpreter with limited syntax.¶

Using a single field complicates parsing and takes a significantly different approach from the existing ones: this can limit adoption.¶

1. Why don’t mention connections?
   
   Beware of the term “connection”:   - it is just one possible saturation cause. Once you go that path  you will expose other infrastructural details (bandwidth, CPU, .. see Section 9.2)  and complicate client compliance;  - it is an infrastructural detail defined in terms of server and network  rather than the consumed service. This specification protects the services first, and then the infrastructures through client cooperation (see Section 9.1).   RateLimit fields enable sending on the same connection different limit values  on each response, depending on the policy scope (eg. per-user, per-custom-key, ..) 
2. Can intermediaries alter RateLimit fields?
   
   Generally, they should not because it might result in unserviced requests. There are reasonable use cases for intermediaries mangling RateLimit fields though, e.g. when they enforce stricter quota-policies, or when they are an active component of the service. In those case we will consider them as part of the originating infrastructure.
3. Why the w parameter is just informative? Could it be used by a client to determine the request rate?
   
   A non-informative w parameter might be fine in an environment where clients and servers are tightly coupled. Conveying policies with this detail on a large scale would be very complex and implementations would be likely not interoperable. We thus decided to leave w as an informational parameter and only rely on RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for defining the throttling behavior.

RFC Editor: Please remove this section before publication. ¶

• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset;
• X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset.

• x-ratelimit-limit-minute, x-ratelimit-limit-hour, x-ratelimit-limit-day
• x-ratelimit-remaining-minute, x-ratelimit-remaining-hour, x-ratelimit-remaining-day

• X-RateLimit-Remaining references different values, depending on the implementation:
  • seconds remaining to the window expiration
  • milliseconds remaining to the window expiration
  • seconds since UTC, in UNIX Timestamp [UNIX]
  • a datetime, either IMF-fixdate [SEMANTICS] or [RFC3339]
• different headers, with the same semantic, are used by different implementers:
  • X-RateLimit-Limit and X-Rate-Limit-Limit
  • X-RateLimit-Remaining and X-Rate-Limit-Remaining
  • X-RateLimit-Reset and X-Rate-Limit-Reset

The semantic of RateLimit-Remaining depends on the windowing algorithm. A sliding window policy for example may result in having a RateLimit-Remaining value related to the ratio between the current and the maximum throughput. Eg.¶

If this is the case, the optimal solution is to achieve¶

At this point you should stop increasing your request rate.¶

RFC Editor: Please remove this section before publication. ¶