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 21 June 2021.¶

Copyright Notice

Copyright (c) 2020 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.¶

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 with the Retry-After header field defined in [SEMANTICS] to be returned in 429 Too Many Requests 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.¶

2. Expressing rate-limit policies

time-window = delta-seconds

   request-quota = quota-units
   quota-units = 1*DIGIT

GET /books/123                  ; request-quota=4, remaining: 3, status=200
GET /books?author=Camilleri     ; request-quota=4, remaining: 1, status=200
GET /books?author=Eco           ; request-quota=4, remaining: 0, status=429

   quota-policy = request-quota; "w" "=" time-window
                  *( OWS ";" OWS quota-comment)
   quota-comment = token "=" (token / quoted-string)

   100;w=60

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

3. Header Specifications

The following RateLimit response fields are defined¶

   RateLimit-Limit = expiring-limit [, 1#quota-policy ]
   expiring-limit = request-quota

   RateLimit-Limit: 100

   RateLimit-Limit: 100, 100;w=10

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

   RateLimit-Remaining = quota-units

   RateLimit-Remaining: 50

   RateLimit-Reset = delta-seconds

   RateLimit-Reset: 50

4. Providing RateLimit headers

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¶

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

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 headers related to the window with the lower RateLimit-Remaining values.¶

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

5. Intermediaries

This section documents the considerations advised in Section 15.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.¶

An intermediary MAY alter the RateLimit fields in such a way as to communicate a more restrictive quota-policy when:¶

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

6. Caching

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 window value of a quota-policy.¶

7. Receiving RateLimit headers

A client MUST process the received RateLimit headers.¶

A client MUST validate the values received in the RateLimit headers 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 request-quota too high.¶

Malformed RateLimit headers 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 informations (eg. the Date response header, 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, the Retry-After header field MUST take precedence and the RateLimit-Reset field MAY be ignored.¶

8. Examples

GET /items/123

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

{"hello": "world"}

GET /items/123

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 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 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 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 200 Ok
Content-Type: application/json
RateLimit-Limit: 100, 100;w=60
Ratelimit-Remaining: 99
Ratelimit-Reset: 50

{"hello": "world"}

GET /items/123

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

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

GET /items/123

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

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

GET /items/123

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

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

GET /items/123

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

{"first": "request"}

GET /items/123

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

{"second": "request"}

GET /items/123

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

{"hello": "world"}

9. Security Considerations

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

10. IANA Considerations

Appendix A. Change Log

RFC EDITOR PLEASE DELETE THIS SECTION.¶

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

Appendix C. RateLimit headers currently used on the web

RFC EDITOR PLEASE DELETE THIS SECTION.¶

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

RateLimit-Limit: 12, 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, 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.¶

Appendix D. FAQ

1. Why defining standard headers 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.¶

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" header to this spec.¶

   I'm open to suggestions: comment on this issue¶

5. Why using delta-seconds instead of a UNIX Timestamp? Why not using subsecond precision?¶

   Using delta-seconds aligns with Retry-After, which is returned in similar contexts, eg on 429 responses.¶

   delta-seconds as defined in [CACHING] section 1.2.1 clarifies some parsing rules too.¶

   Timestamps require a clock synchronization protocol (see [SEMANTICS] section 4.1.1.1). 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. The returned values were used to decide whether to serve or not the current request and do not imply any guarantee that future requests will be successful.¶

   Instead they help to understand when future requests will probably be throttled. A low value for RateLimit-Remaining should be interpreted as a yellow traffic-light for either the number of requests issued in the time-window or the request throughput.¶

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

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

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 header:¶

RateLimit-Limit: 100, 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 header?¶

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 headers is easily parseable, even by implementors procesing responses using technologies like dynamic interpreter with limited syntax.¶

Using a single header 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 headers 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.¶

Authors' Addresses