RateLimit Header Fields for HTTPTeam Digitale, Italian Governmentrobipolli@gmail.comRed Hatamr@redhat.com
General
Internet-DraftThis document defines the RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset header fields for HTTP,
thus allowing servers to publish current request quotas and
clients to shape their request policy and avoid being throttled out.RFC EDITOR: please remove this section before publicationDiscussion of this draft takes place on the HTTP working group mailing list
(ietf-http-wg@w3.org), which is archived at
https://lists.w3.org/Archives/Public/ietf-http-wg/.The source code and issues list for this draft can be found at
https://github.com/ioggstream/draft-polli-ratelimit-headers.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 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.Servers use quota mechanisms to avoid systems overload,
to ensure an equitable distribution of computational resources
or to enforce other policies - eg. monetization.A basic quota mechanism limits the number of acceptable
requests in a given time window, eg. 10 requests per second.When quota is exceeded, servers usually do not serve the request
replying instead with a 4xx HTTP status code (eg. 429 or 403)
or adopt more aggressive policies like dropping connections.Quotas may be enforced on different basis (eg. 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 request per minute;limited to 1000 request per hour.Moreover system metrics, statistics and heuristics can be used
to implement more complex policies, where
the number of acceptable request 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;A major interoperability issue in throttling is the lack
of standard headers, because:each implementation associates different semantics to the
same header field names;header field names proliferates.Client applications interfacing with different servers may thus
need to process different headers,
or the very same application interface that sits behind different
reverse proxies may reply with different throttling headers.This proposal defines syntax and semantics for the following header 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.The behavior of RateLimit-Reset is compatible with the delta-seconds notation of Retry-After.The header fields definition allows to describe complex policies, including the ones
using multiple and variable time windows and dynamic quotas, or implementing concurrency limits.The goals of this proposal are:Standardizing the names and semantic of rate-limit headers;Improve resiliency of HTTP infrastructures simplifying
the enforcement and the adoption of rate-limit headers;Simplify API documentation avoiding expliciting
rate-limit header fields semantic in documentation.The goals do not include:
The rate-limit headers described here are not meant to support
authorization or other kinds of access controls.
This specification does not cover the throttling scope,
that may be the given resource-target, its parent path or the whole
Origin section 7.
The rate-limit headers may be returned in both
Successful and non Successful responses.
This specification does not cover whether non Successful
responses count on quota usage.
This specification does not mandate a specific throttling policy.
The values published in the headers, including the window size,
can be statically or dynamically evaluated.
Conveyed quota hints do not imply any service guarantee.
Server is free to throttle respectful clients under certain circumstances.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
“SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this
document are to be interpreted as described in BCP 14 ( and )
when, and only when, they appear in all capitals, as shown here.This document uses the Augmented BNF defined in and updated
by along with the “#rule” extension defined in Section 7 of
.The term Origin is to be interpreted as described in section 7.The “delta-seconds” rule is defined in section 1.2.1.Rate limit policies limit the number of acceptable requests in a given time window.A time window is expressed in seconds, using the following syntax:Subsecond precision is not supported.The request-quota is a value associated to the maximum number of requests
that the server is willing to accept
from one or more clients
on a given basis (originating IP, authenticated user, geographical, ..)
during a time-window as defined in .The request-quota is expressed in quota-units and has the following syntax:The request-quota SHOULD match the maximum number of acceptable requests.The request-quota MAY differ from the total number of acceptable requests
when weight mechanisms, bursts, or other server policies are implemented.If the request-quota does not match the maximum number of acceptable requests
the relation with that SHOULD be communicated out-of-band.Example: A server couldcount once requests like /books/{id}count twice search requests like /books?author=Camilleriso that we have the following countersThis specification allows describing a quota policy with the following syntax:An example policy of 100 quota-units per minute.Two examples of providing further details via custom parameters
in quota-comments.The following RateLimit response header fields are definedThe RateLimit-Limit response header field indicates
the request-quota associated to the client
in the current time-window.If the client exceeds that limit, it MAY not be served.The header value isThe expiring-limit value MUST be set to the request-quota that is closer to reach its limit.The quota-policy is defined in , and its values are informative.A time-window associated to expiring-limit can be communicated
via an optional quota-policy value, like shown in the following exampleIf the expiring-limit is not associated to a time-window, the time-window MUST either be:inferred by the value of RateLimit-Reset at the moment of the reset, orcommunicated out-of-band (eg. in the documentation).Policies using multiple quota limits MAY be returned using multiple
quota-policy items, like shown in the following two examples:The RateLimit-Remaining response header field indicates the remaining quota-units defined in
associated to the client.The header value isClients MUST NOT assume that a positive RateLimit-Remaining value is
a guarantee of being served.A low RateLimit-Remaining value is like a yellow traffic-light: the red light
may arrive suddenly.One example of RateLimit-Remaining use is below.The RateLimit-Reset response header field indicates eitherthe number of seconds until the quota resets.The header value isThe delta-seconds format is used because:it does not rely on clock synchronization and is resilient to clock adjustment
and clock skew between client and server (see Section 4.1.1.1);it mitigates the risk related to thundering herd when too many clients are serviced with the same timestamp.An example of RateLimit-Reset use is below.The client MUST NOT assume that all its request-quota will be restored
after the moment referenced by RateLimit-Reset.
The server MAY arbitrarily alter the RateLimit-Reset value between subsequent requests
eg. in case of resource saturation or to implement sliding window policies.A server MAY use one or more RateLimit response header 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 header fieldsdoes 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 .A server MAY return RateLimit response header fields independently
of the response status code. This includes throttled responses.If a response contains both the Retry-After and the RateLimit-Reset header fields,
the value of RateLimit-Reset MUST be consistent with the one of 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.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 header fields,
the Retry-After header field MUST take precedence and
the RateLimit-Reset header field MAY be ignored.The client exhausted its request-quota for the next 50 seconds.
The time-window is communicated out-of-band or inferred by the header values.Request:Response:The server uses two custom headers,
namely acme-RateLimit-DayLimit and acme-RateLimit-HourLimit
to expose the following policy:5000 daily quota-units;1000 hourly quota-units.The client consumed 4900 quota-units in the first 14 hours.Despite the next hourly limit of 1000 quota-units, the closest limit
to reach is the daily one.The server then exposes the RateLimit-* headers to
inform the client that:it has only 100 quota-units left;the window will reset in 10 hours.Request:Response:Throttling headers may be used to limit concurrency,
advertising limits that are lower than the usual ones
in case of saturation, thus increasing availability.The server adopted a basic policy of 100 quota-units
per minute,
and in case of resource exhaustion adapts the returned values
reducing both RateLimit-Limit and RateLimit-Remaining.After 2 seconds the client consumed 40 quota-unitsRequest:Response:At the subsequent request - due to resource exhaustion -
the server advertises only RateLimit-Remaining: 20.Request:Response:A client exhausted its quota and the server throttles the request
sending the Retry-After response header field.The values of Retry-After and RateLimit-Reset are consistent as they
reference the same moment.The 429 Too Many Requests HTTP status code is just used as an example.Request:Response:The client has 99 quota-units left for the next 50 seconds.
The time-window is communicated by the w parameter, so we know the throughput is 100 quota-units per minute.Request:Response:The policy conveyed by RateLimit-Limit states that
the server accepts 100 quota-units per minute.Due to resource exhaustion, the server artificially lowers
the actual limits returned in the throttling headers.The current policy then advertises
only 9 quota-units for the next 50 seconds.Note that the server could have lowered even the other
values in RateLimit-Limit: this specification
does not mandate any relation between the field values
contained in subsequent responses.Request:Response:The server does not expose RateLimit-Remaining values, but
resets the limit counter every second.It communicates to the client the limit of 10 quota-units per second
always returning the couple RateLimit-Limit and RateLimit-Reset.Request:Response:Request:Response:This is a standardized way of describing the policy
detailed in :5000 daily quota-units;1000 hourly quota-units.The client consumed 4900 quota-units in the first 14 hours.Despite the next hourly limit of 1000 quota-units, the closest limit
to reach is the daily one.The server then exposes the RateLimit headers to
inform the client that:it has only 100 quota-units left;the window will reset in 10 hours;the expiring-limit is 5000.Request:Response:This specification does not prevent clients to
make over-quota requests.Servers should always implement mechanisms
to prevent resource exhaustion.Servers should not disclose operational capacity informations that
can be used to saturate its resources.While this specification does not mandate whether non 2xx responses
consume quota, if 401 and 403 responses count on quota
a malicious client could probe the endpoint
to get traffic informations of another
user.RateLimit-* headers convey hints from the server
to the clients in order to avoid being throttled out.Clients MUST NOT consider the quota-units returned in RateLimit-Remaining
as a service level agreement.In case of resource saturation, the server MAY artificially lower the returned
values or not serve the request anyway.Consider that request-quota may not be restored after the moment referenced by RateLimit-Reset,
and the RateLimit-Reset value should not be considered fixed nor constant.Subsequent requests may return an higher RateLimit-Reset value to limit
concurrency or implement dynamic or adaptive throttling policies.When returning RateLimit-Reset you must be aware that many throttled
clients may come back at the very moment specified.This is true for Retry-After too.For example, if the quota resets every day at 18:00:00
and your server returns the RateLimit-Reset accordinglythere’s a high probability that all clients will show up at 18:00:00.This could be mitigated adding some jitter to the field-value.RateLimit header fields may assume unexpected values by chance or purpose.
For example, an excessively high RateLimit-Remaining value may be:used by a malicious intermediary to trigger a Denial of Service attack
or consume client resources boosting its requests;passed by a misconfigured server;or an high RateLimit-Reset value could inhibit clients to contact
the server.Clients MUST validate the received values to mitigate those risks.This section registers the RateLimit-Limit header field in the “Permanent Message
Header Field Names” registry ().Header field name: RateLimit-LimitApplicable protocol: httpStatus: standardAuthor/Change controller: IETFSpecification document(s): of this documentThis section registers the RateLimit-Remaining header field in the “Permanent Message
Header Field Names” registry ().Header field name: RateLimit-RemainingApplicable protocol: httpStatus: standardAuthor/Change controller: IETFSpecification document(s): of this documentThis section registers the RateLimit-Reset header field in the “Permanent Message
Header Field Names” registry ().Header field name: RateLimit-ResetApplicable protocol: httpStatus: standardAuthor/Change controller: IETFSpecification document(s): of this documentKey words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Augmented BNF for Syntax Specifications: ABNFInternet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]The Web Origin ConceptThis document defines the concept of an "origin", which is often used as the scope of authority or privilege by user agents. Typically, user agents isolate content retrieved from different origins to prevent malicious web site operators from interfering with the operation of benign web sites. In addition to outlining the principles that underlie the concept of origin, this document details how to determine the origin of a URI and how to serialize an origin into a string. It also defines an HTTP header field, named "Origin", that indicates which origins are associated with an HTTP request. [STANDARDS-TRACK]Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingThe Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.Hypertext Transfer Protocol (HTTP/1.1): Semantics and ContentThe Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.Case-Sensitive String Support in ABNFThis document extends the base definition of ABNF (Augmented Backus-Naur Form) to include a way to specify US-ASCII string literals that are matched in a case-sensitive manner.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.The Single UNIX Specification, Version 2 - 6 Vol Set for UNIX 98Hypertext Transfer Protocol (HTTP/1.1): CachingThe Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.Registration Procedures for Message Header FieldsThis specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Additional HTTP Status CodesThis document specifies additional HyperText Transfer Protocol (HTTP) status codes for a variety of common situations. [STANDARDS-TRACK]Date and Time on the Internet: TimestampsThis document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.RFC EDITOR PLEASE DELETE THIS SECTION.Thanks to Willi Schoenborn, Alejandro Martinez Ruiz, Alessandro Ranellucci,
Erik Wilde and Mark Nottingham for being the initial contributors
of these specifications.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-dayx-ratelimit-remaining-minute, x-ratelimit-remaining-hour, x-ratelimit-remaining-dayHere are some interoperability issues:X-RateLimit-Remaining references different values, depending on the implementation: seconds remaining to the window expirationmilliseconds remaining to the window expirationseconds since UTC, in UNIX Timestampa datetime, either IMF-fixdate or different headers, with the same semantic, are used by different implementers: X-RateLimit-Limit and X-Rate-Limit-LimitX-RateLimit-Remaining and X-Rate-Limit-RemainingX-RateLimit-Reset and X-Rate-Limit-ResetThe 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 achieveAt this point you should stop increasing your request rate.Why defining standard headers for throttling?
To simplify enforcement of throttling policies.Can I use RateLimit-* in throttled responses (eg with status code 429)?
Yes, you can.Are those specs tied to RFC 6585?
No. 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.Why don’t pass the trottling scope as a parameter?
I’m open to suggestions. File an issue if you think it’s worth ;).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 section 1.2.1 clarifies some parsing rules too.
Timestamps require a clock synchronization protocol (see 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 mlalmost all rate-limit headers implementations do not use it.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.Shouldn’t I limit concurrency instead of request rate?
You can do both. The goal of this spec is to provide guidance for
clients in shaping their requests without being throttled out.
Limiting concurrency results in unserviced client requests,
which is something we want to avoid.
A standard 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, ..).
Dynamically lowering the values returned by the rate-limit headers,
and returning retry-after along with them can improve availability.
Saturation conditions can be either dynamic or static: all this is out of
the scope for the current document.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.Is the quota-policy definition too complex?
You can always return the simplest form of the 3 headersThe key runtime value is the first element of the list: expiring-limit, the others quota-policy are informative.
So for the following header:the key value is the one referencing the lowest limit: 100