From 23d474b7c23a1f6b66e444459973e84bc62809b5 Mon Sep 17 00:00:00 2001 From: Tom Paulus Date: Thu, 18 Sep 2025 10:17:51 -0700 Subject: [PATCH 1/2] Update API Rate Limit Fundamentals with IETF Format Headers --- src/content/docs/fundamentals/api/reference/limits.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/content/docs/fundamentals/api/reference/limits.mdx b/src/content/docs/fundamentals/api/reference/limits.mdx index c060316cfb31f58..a6200cf0e5f8ad6 100644 --- a/src/content/docs/fundamentals/api/reference/limits.mdx +++ b/src/content/docs/fundamentals/api/reference/limits.mdx @@ -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. From 77a09eb2c62695e3663633369765df4431776c62 Mon Sep 17 00:00:00 2001 From: Tom Paulus Date: Thu, 18 Sep 2025 10:19:44 -0700 Subject: [PATCH 2/2] Update Changelog for API Rate Limits to include IETF Formatted Headers --- .../fundamentals/2025-09-03-rate-limiting-improvement.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/content/changelog/fundamentals/2025-09-03-rate-limiting-improvement.mdx b/src/content/changelog/fundamentals/2025-09-03-rate-limiting-improvement.mdx index 54b445e356b5ccb..78ffc7cb93ea799 100644 --- a/src/content/changelog/fundamentals/2025-09-03-rate-limiting-improvement.mdx +++ b/src/content/changelog/fundamentals/2025-09-03-rate-limiting-improvement.mdx @@ -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.