RateLimit

The unofficial RateLimit response header reports the current service limits a client has under each named quota policy, including the quota still available and the effective time window for that quota.

Table of Contents

Usage

The RateLimit response header tells a client how much quota is left right now under one or more named policies. It carries the live counters that change from one response to the next, while the companion RateLimit-Policy header advertises the fixed shape of each policy.

The value is a non-empty List in HTTP Structured Fields syntax. Each member is a quoted policy identifier followed by parameters. The r parameter reports the quota still available, and the optional t parameter reports the effective window in seconds: the period within which the client can use no more than the available quota. A server enforcing several policies at once lists each one as a separate member, separated by commas.

The RateLimit field pairs with RateLimit-Policy in the current standardization effort. This two-field pair supersedes the legacy three-header set of RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset, which originated in earlier draft versions and stay in wide use as de facto conventions. A client reading RateLimit alongside its matching policy entry has the full picture needed to pace requests and avoid a 429 response.

Note

The IETF standardization effort (draft-ietf-httpapi-ratelimit-headers) is an active Internet-Draft in the httpapi working group, not yet published as an RFC. The current draft defines two fields, RateLimit and RateLimit-Policy, replacing the three separate RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers from earlier draft versions.

Values

policy identifier

A quoted string naming the policy that the service limit applies to. The identifier matches a member of the RateLimit-Policy field, which links the live counters to the policy that defines the quota and window.

r

The r parameter reports the quota still available under the named policy, expressed as a non-negative integer in quota units. This parameter is required on every member. A value of 0 means the quota is exhausted and further requests are likely to receive a 429 response until the window resets.

t

The t parameter reports the effective window under the named policy as a non-negative integer number of seconds: the period within which the client can use no more than the available quota. This parameter is optional. The value is a duration measured from now, similar to the delta-seconds form used by Retry-After. A client does not assume the full quota is restored once this window passes, since a server may apply a sliding window and adjust the values between responses.

pk

The pk parameter conveys the partition key that the service limit applies to, expressed as a Structured Fields Byte Sequence wrapped in colons. Partition keys let a server scope quota to a tenant, account, or API key while sharing a single policy definition. This parameter is optional.

Example

A single default policy with 50 requests of quota still available and a 30-second effective window. The quoted default identifier matches the policy entry in the RateLimit-Policy header.

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

A response carrying both fields together. The policy entry defines a 100-request quota over a 60-second window, and the live counter shows 42 requests remaining within an 18-second window.

RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=42;t=18

A server enforcing two policies at once. The client has 8 requests left in the burst policy and 743 left in the daily policy, each with its own effective window.

RateLimit: "burst";r=8;t=12, "daily";r=743;t=50400

A partitioned quota scoped by a partition key. The pk parameter carries a Byte Sequence identifying the account the quota applies to, and 300000000 quota units remain.

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

See also

Last updated: June 5, 2026