feat: add rate limiting section

docs/errors/rate-limit-exceeded.mdx

@@ -4,6 +4,29 @@ title: Rate Limit Exceeded (RATE_LIMIT_EXCEEDED)
 
 The request was rejected because the client exceeded the configured rate limit.
 
+## Response format
+
+The 429 response uses the
+[Problem Details](../programmable-api/http-problems.mdx) format:
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/429",
+  "title": "Too Many Requests",
+  "status": 429,
+  "detail": "Rate limit exceeded",
+  "instance": "/your-route",
+  "trace": {
+    "requestId": "4d54e4ee-c003-4d75-aba9-e09a6d707b08",
+    "timestamp": "2026-04-14T12:00:00.000Z",
+    "buildId": "ec44e831-3a02-467e-a26c-7e401e4473bf"
+  }
+}
+```
+
+If `headerMode` is set to `"retry-after"` (the default), the response includes a
+`Retry-After` header with the number of seconds to wait before retrying.
+
 ## Common Causes
 
 - **Too many requests** — The client sent more requests than the rate limit
@@ -24,8 +47,12 @@ The request was rejected because the client exceeded the configured rate limit.
 
 ## For API Operators
 
-- Review the rate limiting policy configuration in the route settings.
+- Review the rate limiting policy configuration in the route settings. Check the
+  `requestsAllowed` and `timeWindowMinutes` values and verify that the
+  `rateLimitBy` identifier is resolving correctly.
 - Consider using
-  [dynamic rate limiting](../articles/step-5-dynamic-rate-limiting.mdx) to set
+  [dynamic rate limiting](../rate-limiting/dynamic-rate-limiting.mdx) to set
   different limits per customer tier.
-- Check the rate limit metrics to determine if limits need adjustment.
+- Use your [logging integration](../articles/logging.mdx) to filter for 429
+  responses and identify which consumers are being throttled. Break down by user
+  or IP to spot noisy neighbors.

docs/programmable-api/zone-cache.mdx

@@ -13,7 +13,7 @@ time-to-live (TTL) after which it expires and is removed from the cache. Each
 cached object can be up to 512 MB in size.
 
 There's an demonstration of ZoneCache use in the
-[Per User Rate Limits Using a Database](../articles/per-user-rate-limits-using-db.mdx)
+[Per User Rate Limits Using a Database](../rate-limiting/per-user-rate-limits-using-db.mdx)
 example.
 
 ## Constructor