docs: document error tracking rate limiting (#17345)

Author: ablaszkiewicz

contents/docs/error-tracking/capture.mdx

@@ -455,6 +455,8 @@ import BurstProtection from './_snippets/burst-protection.mdx'
 
 <BurstProtection />
 
+Burst protection runs client-side, per client. To cap exception volume across your whole project – or per issue – set a server-side [rate limit](/docs/error-tracking/rate-limiting).
+
 ## Common problems
 
 ### Exception steps don't appear in the session timeline

contents/docs/error-tracking/pricing.mdx

@@ -69,3 +69,7 @@ import BurstProtection from './_snippets/burst-protection.mdx'
 import BeforeSendHook from './_snippets/before-send-hook.mdx'
 
 <BeforeSendHook />
+
+### Rate limits
+
+Set a server-side [rate limit](/docs/error-tracking/rate-limiting) to cap how many exceptions PostHog ingests per project or per issue. Exceptions received above the configured rate are dropped at ingestion, so they aren't billed. This is the best way to stop a single noisy client or runaway issue from unexpectedly inflating your bill.

contents/docs/error-tracking/rate-limiting.mdx

@@ -0,0 +1,54 @@
+---
+title: Rate limiting
+---
+
+import { CalloutBox } from 'components/Docs/CalloutBox'
+
+Rate limits cap how many exception events PostHog ingests, so a single noisy client or runaway issue can't blow through your quota – or your bill. Exceptions received above the configured rate are dropped at ingestion, before they're [stored or billed](/docs/error-tracking/pricing).
+
+## How rate limiting works
+
+PostHog applies rate limits using a token bucket. You set a **maximum number of exceptions** and a **time window** (for example, 10,000 exceptions per hour). The bucket holds up to that maximum and refills steadily across the window, so short bursts are absorbed while sustained over-the-limit volume is capped. Exceptions that arrive when the bucket is empty are dropped at ingestion.
+
+Because dropped exceptions are never ingested, they don't count toward your bill.
+
+There are two types of rate limit. They're applied independently, and you can use either or both. You can configure both in the [Error Tracking configuration page](https://app.posthog.com/error_tracking/configuration#selectedSetting=error-tracking-rate-limits).
+
+### Project-wide rate limit
+
+This limit applies across your entire project, regardless of which issue an exception belongs to. It acts as a single safety cap on total exception volume.
+
+<ProductScreenshot
+    imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/pasted_image_2026_06_07_T14_08_44_937_Z_c8badbee44.png"
+    imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/pasted_image_2026_06_07_T14_04_59_591_Z_1f50e085fa.png"
+    alt="Project-wide rate limit settings"
+    classes="rounded"
+/>
+
+### Per-issue rate limit
+
+You set a single limit, and PostHog automatically applies it to every issue individually – each issue gets its own bucket. Once an issue exceeds the configured rate, further exceptions for *that issue* are dropped, while exceptions from your other issues keep flowing. Use this to stop a single noisy issue from drowning out everything else.
+
+When configuring a per-issue limit, you can pick an issue from your most active issues to preview its recent exception volume against the limit, so you can choose a threshold before saving.
+
+<ProductScreenshot
+    imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/pasted_image_2026_06_07_T14_09_34_375_Z_d89669f2f6.png"
+    imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/pasted_image_2026_06_07_T14_10_04_339_Z_652b6381b6.png"
+    alt="Per-issue rate limit settings"
+    classes="rounded"
+/>
+
+## Configuring rate limits
+
+The following options are available for each limit:
+
+| Option | Description |
+| --- | --- |
+| **Maximum exceptions** | The most exceptions to ingest per window. Leave this empty for no limit. |
+| **Per** | The time window the limit applies over – 15 minutes, 30 minutes, or 1 hour. |
+
+<CalloutBox icon="IconInfo" title="Rate limits vs. client-side controls" type="fyi">
+
+Rate limits run server-side, at ingestion, and apply to every client sending exceptions to your project. To reduce exceptions before they leave the client, see [burst protection](/docs/error-tracking/capture#burst-protection), [suppression rules](/docs/error-tracking/capture#suppressing-exceptions), and the [`before_send` hook](/docs/error-tracking/capture). For more ways to lower your bill, see [reducing Error Tracking costs](/docs/error-tracking/pricing).
+
+</CalloutBox>

src/navs/index.js

@@ -5050,6 +5050,13 @@ export const docsMenu = {
                     color: 'yellow',
                     featured: true,
                 },
+                {
+                    name: 'Rate limiting',
+                    url: '/docs/error-tracking/rate-limiting',
+                    icon: 'IconThrottle',
+                    color: 'orange',
+                    featured: true,
+                },
                 {
                     name: 'Code variables',
                     url: '/docs/error-tracking/code-variables',