RateLimit-Policy

The unofficial RateLimit-Policy response header advertises the server's quota policies, naming each policy and stating its quota size, time window, quota unit, and optional partition key.

Table of Contents

Usage

The RateLimit-Policy response header describes the fixed shape of each rate limit a server enforces. It names each policy and states how much quota the policy allocates, over what time window, and in what units. The companion RateLimit header then reports the live counters for those same policies on each response.

The value is a non-empty List in HTTP Structured Fields syntax. Each member is a quoted policy identifier followed by parameters. The required q parameter sets the quota, the optional w parameter sets the window in seconds, the optional qu parameter names the quota unit, and the optional pk parameter carries a partition key. A server advertising several policies lists each one as a separate member, separated by commas.

The RateLimit-Policy field pairs with RateLimit 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. The policy field stays consistent across a sequence of responses, giving clients a stable reference for how each quota behaves.

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. The identifier ties the policy definition to the matching live counters in the RateLimit field, so a client knows which quota each counter belongs to.

q

The q parameter sets the quota the policy allocates, expressed as a non-negative integer in quota units. This parameter is required on every member. It defines the ceiling that the available quota in RateLimit counts down from.

qu

The qu parameter names the quota unit that q is measured in, expressed as a quoted string. This parameter is optional and defaults to requests. Servers metering by payload size or another resource set a unit such as content-bytes.

w

The w parameter sets the time window over which the quota applies, expressed as a non-negative integer number of seconds. This parameter is optional. A window of 60 means the policy allocates q quota units every 60 seconds.

pk

The pk parameter conveys the partition key the policy applies to, expressed as a Structured Fields Byte Sequence wrapped in colons. Partition keys scope a shared policy to a specific tenant, account, or API key. This parameter is optional.

Example

A single default policy allocating 100 requests over a 10-second window. The quoted default identifier matches the counters reported in the RateLimit header.

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

A server advertising two policies at once. The burst policy allows 100 requests per minute, and the daily policy allows 1000 requests per day.

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

A per-user policy scoped by a partition key. The pk parameter carries a Byte Sequence identifying the user the quota applies to.

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

A policy metering by payload size rather than request count. The qu parameter sets the unit to content-bytes, so the 65535 quota counts bytes instead of requests.

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

See also

Last updated: June 5, 2026