Skip to content

Update API Rate Limit Headers to reflect IETF Proposal #25269

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 18, 2025
Merged

Update API Rate Limit Headers to reflect IETF Proposal #25269

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
23d474b
Update API Rate Limit Fundamentals with IETF Format Headers
tpaulus Sep 18, 2025
77a09eb
Update Changelog for API Rate Limits to include IETF Formatted Headers
tpaulus Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions src/content/changelog/fundamentals/2025-09-03-rate-limiting-improvement.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,14 @@ As always, if you need any help with rate limits, please contact Support.
#### New Headers

**Headers that are always returned:**
- X-RateLimit-Limit: Total Number of requests the caller can make
- X-RateLimit-Remaining: Number of requests before Rate Limit kicks in
- `Ratelimit`: List of service limit items, composed of the limit name, the remaining quota (`r`) and the time next window resets (`t`). For example: `"default";r=50;t=30`
- `Ratelimit-Policy`: List of quota policy items, composed of the policy name, the total quota (`q`) and the time window the quota applies to (`w`). For example: `"burst";q=100;w=60`

**Returned only when a rate limit has been reached (error code: 429):**
- Retry-After: Number of Seconds until more capacity is available, rounded up
- X-RateLimit-Reset: RFC 1123 Formatted Date as to when more capacity is available

#### SDK Back offs
- All SDKs will automatically respond to the headers, instituting a backoff when limits are approached.
- All of Cloudflare's latest SDKs will automatically respond to the headers, instituting a backoff when limits are approached.

### GraphQL and Edge APIs
These new headers and back offs are only available for Cloudflare REST APIs, and will not affect GraphQL.
Expand Down
7 changes: 3 additions & 4 deletions src/content/docs/fundamentals/api/reference/limits.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,8 @@ import { Render } from "~/components";

The following headers are returned when calling REST APIs:

- `ratelimit-limit`: The total number of requests a caller can make.
- `ratelimit-remaining`: The number of remaining requests before the rate limit takes effect.
- `retry-after`: The number of seconds, rounded up, until more capacity is available.
- `ratelimit-reset`: The `RFC 1123` formatted date when more capacity is available.
- `Ratelimit`: List of service limit items, composed of the limit name, the remaining quota (`r`) and the time next window resets (`t`). For example: `"default";r=50;t=30`
- `Ratelimit-Policy`: List of quota policy items, composed of the policy name, the total quota (`q`) and the time window the quota applies to (`w`). For example: `"burst";q=100;w=60`
- `retry-after`: The number of seconds, rounded up, until more capacity is available. Note, this header is only returned when the request has exceeded the rate limit.

Cloudflare's SDKs will also automatically work with the headers and back off in response to rate limits.
Loading