RateLimit header 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 26 December 2023.¶

Copyright Notice

Copyright (c) 2023 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

Rate limiting HTTP clients has become a widespread practice, especially for HTTP APIs. Typically, servers who do so limit the number of acceptable requests in a given time window (e.g. 10 requests per second). See Appendix A for further information on the current usage of rate limiting in HTTP.¶

Currently, there is no standard way for servers to communicate quotas so that clients can throttle its requests to prevent errors. This document defines a set of standard HTTP header fields to enable rate limiting:¶

• RateLimit: to convey the server's current limit of quota units available to the client in the policy time window, the remaining quota units in the current window, and the time remaining in the current window, specified in seconds, and¶
• RateLimit-Policy: the service policy limits.¶

These fields allow the establishment of complex rate limiting policies, including using multiple and variable time windows and dynamic quotas, and implementing concurrency limits.¶

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

2. Concepts

   100;w=60

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;comment="fixed window"
   12;w=1;burst=1000;policy="leaky bucket"

3. RateLimit header field Definitions

The following RateLimit response header fields are defined.¶

   limit=100

   remaining=50

   reset=50

   RateLimit-Policy: 100;w=10
   RateLimit: limit=100, remaining=50, reset=5

   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-Policy: 10;w=1, 10;w=60

4. Server Behavior

A server uses the RateLimit header fields to communicate its quota policies. A response that includes the RateLimit-Limit header field MUST also include the RateLimit-Reset. It MAY also include a RateLimit-Remaining header field.¶

A server MAY return RateLimit header fields independently of the response status code. This includes on throttled responses. This document does not mandate any correlation between the RateLimit header field values and the returned status code.¶

Servers should be careful when returning RateLimit header fields in redirection responses (i.e., responses with 3xx status codes) because a low remaining keyword value could prevent the client from issuing requests. For example, given the RateLimit header 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 remaining keyword value is 0.¶

HTTP/1.1 301 Moved Permanently
Location: /foo/123
RateLimit: limit=10, remaining=0, reset=10

If a response contains both the Retry-After and the RateLimit header fields, the reset keyword 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 header fields related to the time window with the lower remaining keyword values.¶

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 keyword values (see Section 6.5); this is especially important when a quota policy uses a large time window.¶

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

5. Client Behavior

The RateLimit header fields can be used by clients to determine whether the associated request respected the server's quota policy, and as an indication of whether subsequent requests will. However, the server might apply other criteria when servicing future requests, and so the quota policy may not completely reflect whether they will succeed.¶

For example, a successful response with the following fields:¶

   RateLimit: limit=10, remaining=1, reset=7

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

A client is responsible for ensuring that RateLimit header field values returned cause reasonable client behavior with respect to throughput and latency (see Section 6.5 and Section 6.5.1).¶

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

Malformed RateLimit header fields MUST be ignored.¶

A client SHOULD NOT exceed the quota units conveyed by the remaining keyword before the time window expressed in the reset keyword.¶

A client MAY still probe the server if the reset keyword is considered too high.¶

The value of the reset keyword 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 reset keyword moment intended by the server.¶

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

If a response contains both the RateLimit and Retry-After fields, the Retry-After field MUST take precedence and the reset keyword 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.¶

6. Security Considerations

   Date: Tue, 15 Nov 1994 08:00:00 GMT
   RateLimit: limit=1, remaining=1, reset=36000

RateLimit: limit=10000, remaining=10000, reset=10
RateLimit-Policy: 10000;w=1000

7. Privacy Considerations

Clients that act upon a request to rate limit are potentially re-identifiable (see Section 5.2.1 of [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 header 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, remaining=0, 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, remaining=0, 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, remaining=100, 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, remaining=60, 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, remaining=20, 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: limit=100, remaining=0, reset=5

{
"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, remaining=99, reset=50
RateLimit-Policy: 100;w=60
{"hello": "world"}

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

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit: limit=10, remaining=9, reset=50
RateLimit-Policy: 100;w=60

{
  "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, remaining=0, reset=20
RateLimit-Policy: 15;w=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, remaining=15, reset=40
RateLimit-Policy: 100;w=60

{
  "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, 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, 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, remaining=100, reset=36000
RateLimit-Policy: 1000;w=3600, 5000;w=86400

{"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 header 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 header 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 5), 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 the remaining and reset keywords.¶

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 remaining keyword imply any service guarantee for my future requests to be served?¶

   No. FAQ integrated in Section 3.3.¶

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

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

RateLimit: limit=100, remaining=50, 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, remaining=50, reset=44
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 header 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 header fields?¶

   Generally, they should not because it might result in unserviced requests. There are reasonable use cases for intermediaries mangling RateLimit header 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 the limit, remaining and reset keywords for defining the throttling behavior.¶

4. Can I use RateLimit fields in trailers? 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. Supporting trailers has the only advantage that allows to provide more up-to-date information to the client in case of slow responses. However, this complicates client implementations with respect to combining fields from headers and accounting for intermediaries that drop trailers. Since there are no current implementations that use trailers, we decided to leave this as a future-work.¶

RateLimit header 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 depends on the windowing algorithm. A sliding window policy for example may result in having a remaining keyword value related to the ratio between the current and the maximum throughput. e.g.¶

RateLimit: limit=12,    \
           remaining=6, \ ; using 50% of throughput, that is 6 units/s
           reset=1
RateLimit-Policy: 12;w=1

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

RateLimit: limit=12,   \
           remaining=1 \  ; using 100% of throughput, that is 12 units/s
           reset=1
RateLimit-Policy: 12;w=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