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 10 April 2025.¶

Copyright Notice

Copyright (c) 2024 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 of 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 their requests to prevent errors. This document defines a set of standard HTTP header fields to enable rate limiting:¶

• RateLimit-Policy: a quota policy, defined by the server, that client HTTP requests will consume.¶

• RateLimit: the currently remaining quota available for a specific policy.¶

These fields enable establishing complex rate limiting policies, including using multiple and variable time windows and dynamic quotas, and implementing concurrency limits.¶

2. Terminology

Quota:

A quota is an allocation of capacity used by a resource server to limit client requests. That capacity is measured in quota units and may be reallocated at the end of a time window.¶

Quota Unit:

A quota unit is the unit of measure used to measure the activity of a client.¶

Quota Partition:

A quota partition is a division of a server's capacity across different clients, users and owned resources.¶

Time Window:

A time window indicates a period of time associated to the allocated quota.¶

Quota Policy:

A quota policy is implemented by the server to regulate the activity within a specified quota partition, quantified in quota units, over a defined time window. This activity is restricted to a predefined limit, known as the quota. 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.¶

Service Limit:

A service limit is the currently remaining quota from a specific quota policy and, if defined, the remaining time before quota is reallocated.¶

3. RateLimit-Policy Field

The "RateLimit-Policy" response header field is a non-empty List of Quota Policy Items (Section 3.1). The Item value MUST be a String. Its value is informative. The field value is expected to remain consistent over a the lifetime of a connection. It is this characteristic that differentiates it from the RateLimit (Section 4) field that contains information that may change on every request.¶

   RateLimit-Policy: "burst";q=100;w=60,"daily";q=1000;w=86400

   RateLimit-Policy: "default";q=100;w=10

   RateLimit-Policy: "permin";q=50;w=60,"perhr";q=1000;w=3600

   RateLimit-Policy: "peruser";q=100;w=60;pk=:cHsdsRa894==:

   RateLimit-Policy: "peruser";q=65535;qu="bytes";w=10;pk=:sdfjLJUOUH==:

4. RateLimit Field

A server uses the "RateLimit" response header field to communicate the service limit for a quota policy for a particular partition key.¶

The field is expressed as List of Service Limit Items (Section 4.1).¶

   RateLimit: "default";r=50;t=30

   RateLimit: "default";r=50;t=30

   RateLimit: "default";r=999;pk=:dHJpYWwxMjEzMjM=:

   RateLimit: "default";r=300000000;t=60;pk=:QXBwLTk5OQ==:

5. Server Behavior

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 parameter 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 parameter value is 0.¶

HTTP/1.1 301 Moved Permanently
Location: /foo/123
RateLimit: "problemPolicy";r=0;t=10

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

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

6. 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 requests will succeed.¶

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

   RateLimit: "default";r=1;t=7

does not guarantee that the next request will be successful. Servers' behavior may be subject to other conditions.¶

A client is responsible for ensuring that RateLimit header field values returned cause reasonable client behavior with respect to throughput and latency (see Section 7.5 and Section 7.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 parameter before the time window expressed in the reset parameter.¶

The value of the reset parameter 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 parameter 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 parameter MAY be ignored.¶

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

• slowing down or pre-emptively back-off their request rate when approaching quota limits;¶

• consuming all the quota according to the exposed limits and then wait.¶

7. Security Considerations

   Date: Tue, 15 Nov 1994 18:00:00 GMT
   RateLimit: "daily";r=1;t=36400

RateLimit-Policy: "somepolicy";q=10000;w=1000
RateLimit: "somepolicy";r=10000;t=10

8. 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.¶

9. 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]):¶

10. References

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: "default";r=0;t=50

{"hello": "world"}

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

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit: "default";r=0;t=48

{"still": "successful"}

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

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit: "dayLimit";r=100;t=36000

{"hello": "world"}

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

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Policy: "basic";q=100;w=60
RateLimit: "basic";r=60;t=58

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

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

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Policy: "basic";q=100;w=60
RateLimit: "basic";r=20;t=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: "default";r=0;t=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: "fixedwindow";r=99;t=50
RateLimit-Policy: "fixedwindow";q=100;w=60
{"hello": "world"}

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

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Policy: "dynamic";q=100;w=60
RateLimit: "dynamic";r=9;t=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-Policy: "dynamic";q=15;w=20
RateLimit: "dynamic";r=0;t=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-Policy: "dynamic";q=100;w=60
RateLimit: "dynamic";r=15;t=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-Policy: quota;q=100;w=1
RateLimit: quota;t=1

{"first": "request"}

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

HTTP/1.1 200 Ok
Content-Type: application/json
RateLimit-Policy: quota;q=10
RateLimit: quota;t=1

{"second": "request"}

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

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Policy: "hour";q=1000;w=3600, "day";q=5000;w=86400
RateLimit: "day";r=100;t=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 and enable clients to constraint their requests to avoid being throttled.¶

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

4. Why is the partition key necessary?¶

   Without a partition key, a server can only effectively only have one scope (aka partition), which is impractical for most services, or it needs to communicate the scopes out-of-band. This prevents the development of generic connector code that can be used to prevent requests from being throttled. Many APIs rely on API keys, user identity or client identity to allocate quota. As soon as a single client processes requests for more than one partition, the client needs to know the corresponding partition key to properly track requests against allocated quota.¶

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

7. Do a positive value of remaining paramter imply any service guarantee for my future requests to be served?¶

   No. FAQ integrated in Section 4.1.1.¶

8. Is the quota-policy definition too complex?¶

   You can always return the simplest form¶

RateLimit:"default";r=50;t=60

The policy key clearly connects the current usage status of a policy to the defined limits. So for the following field:¶

RateLimit-Policy: "sliding";q=100;w=60;burst=1000
RateLimit-Policy: "fixed";q=5000;w=3600;burst=0
RateLimit: "sliding";r=50;t=44

the value "sliding" identifies the policy being reported.¶

1. 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.¶

2. 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 parameters for defining the throttling behavior.¶

3. 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;¶

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 parameter value related to the ratio between the current and the maximum throughput. e.g.¶

RateLimit-Policy: "sliding";q=12;w=1
; using 50% of throughput, that is 6 units/s
RateLimit: "sliding";q=12;r=6;t=1

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

RateLimit-Policy: "sliding";q=12;w=1
; using 100% of throughput, that is 12 units/s
RateLimit: "sliding";q=12;r=1;t=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, and Julian Reschke.¶

Changes

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

Authors' Addresses