From d575fb64fe515f60605a4fac89bdc0c6626fa574 Mon Sep 17 00:00:00 2001
From: Nic <123965403+ngayerie@users.noreply.github.com>
Date: Tue, 9 Sep 2025 15:47:55 +0100
Subject: [PATCH] [Fundamentals] Update api-rate-limits.mdx

PCX-18463
Documenting the new headers in the dev docs

From https://developers.cloudflare.com/changelog/2025-09-03-rate-limiting-improvement/
---
 src/content/partials/fundamentals/api-rate-limits.mdx | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/content/partials/fundamentals/api-rate-limits.mdx b/src/content/partials/fundamentals/api-rate-limits.mdx
index 2c5eb6926c30745..1dd7e6c007d2c34 100644
--- a/src/content/partials/fundamentals/api-rate-limits.mdx
+++ b/src/content/partials/fundamentals/api-rate-limits.mdx
@@ -32,3 +32,13 @@ Some specific API calls have their own limits and are documented separately, suc
 - [Gateway Lists API](/cloudflare-one/policies/gateway/lists/#api-rate-limit)
 
 Enterprise customers can also [contact Cloudflare Support](/support/contacting-cloudflare-support/) to raise the Client API per user, GraphQL, or API token limits to a higher value.
+
+The following headers that are always returned on calls to the Cloudflare API:
+
+ - `X-RateLimit-Limit`: Total Number of requests the caller can make
+ - `X-RateLimit-Remaining`: Number of requests before Rate Limit kicks in
+
+And these headers are 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