RateLimit Fields for HTTP

Status of This Memo

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 7 January 2023.¶

Copyright Notice

Copyright (c) 2022 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 Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

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 [HTTP] to be returned in 429 (Too Many Request) (see [STATUS429]) or 503 (Service Unavailable) responses.¶

Widely deployed quota mechanisms limit the number of acceptable requests in a given time window, e.g. 10 requests per second; currently, there is no standard way to communicate service quotas so that the client can throttle its requests and prevent 4xx or 5xx responses. See Appendix A for further information on the current usage of rate limiting in HTTP.¶

This document defines syntax and semantics for the following fields:¶

• RateLimit-Limit: containing the requests quota in the time window;¶
• RateLimit-Remaining: containing the remaining requests quota in the current window;¶
• RateLimit-Reset: containing the time remaining in the current window, specified in seconds;¶
• RateLimit-Policy: containing the quota policy information.¶

The behavior of the RateLimit-Reset field is compatible with the delay-seconds notation of Retry-After.¶

The fields definition allows to describe complex policies, including the ones using multiple and variable time windows and dynamic quotas, or implementing concurrency limits.¶

2. Expressing rate-limit policies

GET /books/123           ; service-limit=4, remaining: 3, status=200
GET /books?author=WuMing ; service-limit=4, remaining: 1, status=200
GET /books?author=Eco    ; service-limit=4, remaining: 0, status=429

   100;w=60

   100;w=60;comment="fixed window"
   12;w=1;burst=1000;policy="leaky bucket"

3. Providing RateLimit fields

A server uses the RateLimit fields to communicate its quota policies according to the following rules:¶

• RateLimit-Limit and RateLimit-Reset fields are REQUIRED;¶
• RateLimit-Remaining field is RECOMMENDED.¶

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¶

   RateLimit-Limit: 10
   RateLimit-Remaining: 1
   RateLimit-Reset: 7

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 fields independently of the response status code. This includes throttled responses.¶

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

Servers should be careful in returning RateLimit fields in redirection responses (e.g. 3xx status codes) because a low RateLimit-Remaining field value could prevent the client from issuing requests. For example, given the RateLimit fields below, a client could decide to wait 10 seconds before following the "Location" header field (see Section 10.2.2 of [HTTP]), because the RateLimit-Remaining field value is 0.¶

HTTP/1.1 301 Moved Permanently
Location: /foo/123
RateLimit-Remaining: 0
RateLimit-Limit: 10
RateLimit-Reset: 10

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

When using a policy involving more than one time-window, the server MUST reply with the RateLimit fields related to the time window with the lower RateLimit-Remaining field 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 field values (see Section 6.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, e.g. 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.¶

4. Receiving 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 field moment too far in the future (e.g. similarly to receiving "Retry-after: 1000000") 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 conveyed by the RateLimit-Remaining field before the time-window expressed in RateLimit-Reset field.¶

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

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

The details provided in RateLimit-Policy field are informative and MAY be ignored.¶

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

This specification does not mandate a specific throttling behavior and implementers can adopt their preferred policies, including:¶

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

5. Fields definition

The following RateLimit response fields are defined¶

   RateLimit-Limit: 100

   RateLimit-Policy: 100;w=10
   RateLimit-Limit: 100

   RateLimit-Policy: 10;w=1, 50;w=60, 1000;w=3600, 5000;w=86400
   RateLimit-Policy: 10;w=1;burst=1000, 1000;w=3600

   RateLimit-Remaining: 50

   RateLimit-Reset: 50

6. Security Considerations

   Date: Tue, 15 Nov 1994 08:00:00 GMT
   RateLimit-Reset: 36000

RateLimit-Limit: 10000
RateLimit-Policy: 10000;w=1000
RateLimit-Remaining: 10000
RateLimit-Reset: 10

7. Privacy Considerations

Clients that act upon a request to rate limit are potentially re-identifiable (see Section 7.1 of [DNS-PRIVACY]) because they react to information that might only be given to them. Note that this might apply to other fields too (e.g. Retry-After).¶

Since rate limiting is usually implemented in contexts where clients are either identified or profiled (e.g. assigning different quota units to different users), this is rarely a concern.¶

Privacy enhancing infrastructures using RateLimit fields can define specific techniques to mitigate the risks of re-identification.¶

8. IANA Considerations

IANA is requested to update one registry and create one new registry.¶

Please add the following entries to the "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry ([HTTP]):¶

Appendix A. Rate-limiting and quotas

Servers use quota mechanisms to avoid systems overload, to ensure an equitable distribution of computational resources or to enforce other policies - e.g. monetization.¶

A basic quota mechanism limits the number of acceptable requests in a given time window, e.g. 10 requests per second.¶

When quota is exceeded, servers usually do not serve the request replying instead with a 4xx HTTP status code (e.g. 429 or 403) or adopt more aggressive policies like dropping connections.¶

Quotas may be enforced on different basis (e.g. per user, per IP, per geographic area, ..) and at different levels. For example, an user may be allowed to issue:¶

• 10 requests per second;¶
• limited to 60 requests per minute;¶
• limited to 1000 requests per hour.¶

Moreover system metrics, statistics and heuristics can be used to implement more complex policies, where the number of acceptable requests and the time window are computed dynamically.¶

To help clients throttling their requests, servers may expose the counters used to evaluate quota policies via HTTP header fields.¶

Those response headers may be added by HTTP intermediaries such as API gateways and reverse proxies.¶

On the web we can find many different rate-limit headers, usually containing the number of allowed requests in a given time window, and when the window is reset.¶

The common choice is to return three headers containing:¶

• the maximum number of allowed requests in the time window;¶
• the number of remaining requests in the current window;¶
• the time remaining in the current window expressed in seconds or as a timestamp;¶

Appendix B. Examples

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 100
Ratelimit-Remaining: 0
Ratelimit-Reset: 50

{"hello": "world"}

GET /items/456 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 100
Ratelimit-Remaining: 0
Ratelimit-Reset: 48

{"still": "successful"}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
acme-RateLimit-DayLimit: 5000
acme-RateLimit-HourLimit: 1000
RateLimit-Limit: 5000
RateLimit-Remaining: 100
RateLimit-Reset: 36000

{"hello": "world"}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 100
RateLimit-Remaining: 60
RateLimit-Reset: 58

{"elapsed": 2, "issued": 40}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 100
RateLimit-Remaining: 20
RateLimit-Reset: 56

{"elapsed": 4, "issued": 41}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Date: Mon, 05 Aug 2019 09:27:00 GMT
Retry-After: Mon, 05 Aug 2019 09:27:05 GMT
RateLimit-Reset: 5
RateLimit-Limit: 100
Ratelimit-Remaining: 0

{
"title": "Too Many Requests",
"status": 429,
"detail": "You have exceeded your quota"
}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 100
RateLimit-Policy: 100;w=60
Ratelimit-Remaining: 99
Ratelimit-Reset: 50

{"hello": "world"}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 10
RateLimit-Policy: 100;w=60
Ratelimit-Remaining: 9
Ratelimit-Reset: 50

{
  "status": 200,
  "detail": "Just slow down without waiting."
}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 0
RateLimit-Policy: 15;w=20
Ratelimit-Remaining: 0
Ratelimit-Reset: 20

{
  "status": 429,
  "detail": "Wait 20 seconds, then slow down!"
}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 20
RateLimit-Limit: 15
RateLimit-Policy: 100;w=60
Ratelimit-Remaining: 15
Ratelimit-Reset: 40

{
  "status": 429,
  "detail": "Wait 20 seconds, then slow down!"
}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 10
Ratelimit-Reset: 1

{"first": "request"}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Limit: 10
Ratelimit-Reset: 1

{"second": "request"}

GET /items/123 HTTP/1.1
Host: api.example

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 5000
RateLimit-Policy: 1000;w=3600, 5000;w=86400
RateLimit-Remaining: 100
RateLimit-Reset: 36000

{"hello": "world"}

FAQ

This section is to be removed before publishing as an RFC.¶

1. Why defining standard fields for throttling?¶

   To simplify enforcement of throttling policies.¶

2. Can I use RateLimit fields 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?¶

   The word "scope" can have different meanings: for example it can be an URL, or an authorization scope. Since authorization is out of the scope of this document (see Section 1.1), and that we rely only on [HTTP], in Section 1.1 we defined "scope" in terms of URL.¶

   Since clients are not required to process quota policies (see Section 4), we could add a new "RateLimit-Scope" field to this spec. See this discussion on a similar thread¶

   Specific ecosystems can still bake their own prefixed parameters, such as acme-auth-scope or acme-url-scope and ensure that clients process them. This behavior cannot be relied upon when communicating between different ecosystems.¶

   We are 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 [HTTP]). This may be problematic (e.g. 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 (e.g. 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 (e.g. 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 field imply any service guarantee for my future requests to be served?¶

   No. FAQ integrated in Section 5.3.¶

9. Is the quota-policy definition Section 2.3 too complex?¶

   You can always return the simplest form of the 3 fields¶

RateLimit-Limit: 100
RateLimit-Remaining: 50
RateLimit-Reset: 60

The key runtime value is the first element of the list: expiring-limit, the others quota-policy are informative. So for the following field:¶

RateLimit-Limit: 100
RateLimit-Policy: 100;w=60;burst=1000;comment="sliding window", 5000;w=3600;burst=0;comment="fixed window"

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 implementers processing 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 6.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 6.1).   RateLimit fields enable sending on the same connection different limit values  on each response, depending on the policy scope (e.g. 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 field and RateLimit-Reset field for defining the throttling behavior.¶

RateLimit fields currently used on the web

This section is to be removed before publishing as an RFC.¶

Commonly used header field names are:¶

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

There are variants too, where the window is specified in the header field name, eg:¶

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

Here are some interoperability issues:¶

• 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 [HTTP] 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 field value related to the ratio between the current and the maximum throughput. e.g.¶

RateLimit-Limit: 12
RateLimit-Policy: 12;w=1
RateLimit-Remaining: 6          ; using 50% of throughput, that is 6 units/s
RateLimit-Reset: 1

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

RateLimit-Limit: 12
RateLimit-Policy: 12;w=1
RateLimit-Remaining: 1          ; using 100% of throughput, that is 12 units/s
RateLimit-Reset: 1

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

Acknowledgements

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 implementers: Aapo Talvensaari, Nathan Friedly and Sanyam Dogra.¶

In addition to the people above, this document owes a lot to the extensive discussion in the HTTPAPI workgroup, including Rich Salz, Darrel Miller and Julian Reschke.¶

Changes

This section is to be removed before publishing as an RFC.¶

Authors' Addresses