RateLimit-Policy

General Summary

Describes the rate limit policy including quota and time window duration.

Detailed Description

The RateLimit-Policy response header provides a structured description of the rate limiting policy applied to the client. It communicates both the quota (maximum number of requests) and the time window in a single header using a standardized format. This header is part of the IETF RateLimit Header Fields specification and allows servers to clearly communicate their rate limiting rules.

The typical format is quota;w=window where quota is the number of requests and window is the time period in seconds.

Use Cases (When, Why, and How)

When to Use It

Include this header when you want to explicitly communicate your rate limiting policy to clients, especially when using the standardized RateLimit-* headers. It’s particularly useful when different endpoints or API tiers have different rate limits.

Why to Use It

This header allows clients to understand the rate limiting policy upfront without having to infer it from RateLimit-Limit and RateLimit-Reset values. It’s especially valuable for documenting API behavior and helping developers implement proper rate limit handling.

How to Use It

Set this header with your rate limit quota and window duration. Multiple policies can be specified if you have different rate limit tiers.

Example code in Javascript:

fetch('https://api.example.com/data')
  .then(response => {
    const policy = response.headers.get('RateLimit-Policy');
    console.log(`Rate limit policy: ${policy}`);
    // Example output: "100;w=60" means 100 requests per 60 seconds
    return response.json();
  });

Example

RateLimit-Policy: 100;w=60

This indicates 100 requests per 60-second window.

RateLimit-Policy: 1000;w=3600, 10000;w=86400

This indicates multiple policies: 1000 requests per hour and 10000 requests per day.