From 97b93f20709ed48cf476f3bfdb38b0bfd0458ef9 Mon Sep 17 00:00:00 2001 From: ablaszkiewicz Date: Sun, 7 Jun 2026 15:00:41 +0200 Subject: [PATCH 1/6] docs: document error tracking rate limiting Add a docs page covering project-wide and per-issue rate limits for error tracking, plus cross-links from the cost-cutting (pricing) page and the client-side burst protection section. Co-Authored-By: Claude Opus 4.8 --- contents/docs/error-tracking/capture.mdx | 2 + contents/docs/error-tracking/pricing.mdx | 4 ++ .../docs/error-tracking/rate-limiting.mdx | 54 +++++++++++++++++++ src/navs/index.js | 7 +++ 4 files changed, 67 insertions(+) create mode 100644 contents/docs/error-tracking/rate-limiting.mdx diff --git a/contents/docs/error-tracking/capture.mdx b/contents/docs/error-tracking/capture.mdx index 8686a520987c..1184bd626840 100644 --- a/contents/docs/error-tracking/capture.mdx +++ b/contents/docs/error-tracking/capture.mdx @@ -455,6 +455,8 @@ import BurstProtection from './_snippets/burst-protection.mdx' +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 diff --git a/contents/docs/error-tracking/pricing.mdx b/contents/docs/error-tracking/pricing.mdx index 75ddc5f2b85e..46e6cac8389b 100644 --- a/contents/docs/error-tracking/pricing.mdx +++ b/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' + +### 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. diff --git a/contents/docs/error-tracking/rate-limiting.mdx b/contents/docs/error-tracking/rate-limiting.mdx new file mode 100644 index 000000000000..d5639cdc0ffa --- /dev/null +++ b/contents/docs/error-tracking/rate-limiting.mdx @@ -0,0 +1,54 @@ +--- +title: Rate limit exception ingestion +--- + +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. + +{/* SCREENSHOT: rate limiting overview / how the token bucket caps volume */} + +There are two types of rate limit. They're applied independently, and you can use either or both. + +### 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. + +{/* SCREENSHOT: project-wide rate limit settings + volume chart */} + +### Per-issue rate limit + +This limit applies to each issue individually. 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. The per-issue limit is checked before the project-wide limit, so a runaway issue is dropped against its own bucket instead of draining your whole project budget on the way out. + +{/* SCREENSHOT: per-issue rate limit settings with issue list + volume preview */} + +## Configuring rate limits + +You can configure rate limits in the [error tracking configuration page](https://app.posthog.com/error_tracking/configuration#selectedSetting=error-tracking-rate-limits). + +{/* SCREENSHOT: rate limits configuration section */} + +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. | + +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. + +{/* SCREENSHOT: per-issue volume preview chart */} + + + +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). + + diff --git a/src/navs/index.js b/src/navs/index.js index 007d5ebf8c69..e1aec4ce72a5 100644 --- a/src/navs/index.js +++ b/src/navs/index.js @@ -5050,6 +5050,13 @@ export const docsMenu = { color: 'yellow', featured: true, }, + { + name: 'Rate limit ingestion', + url: '/docs/error-tracking/rate-limiting', + icon: 'IconThrottle', + color: 'orange', + featured: true, + }, { name: 'Code variables', url: '/docs/error-tracking/code-variables', From dd7cbb75b751466a838511b1ef57afc96ff10be3 Mon Sep 17 00:00:00 2001 From: ablaszkiewicz Date: Sun, 7 Jun 2026 16:10:47 +0200 Subject: [PATCH 2/6] docs: add rate limit settings screenshots Replace screenshot placeholders with the project-wide and per-issue settings screenshots; drop the remaining placeholders. Co-Authored-By: Claude Opus 4.8 --- .../docs/error-tracking/rate-limiting.mdx | 28 ++++++++++--------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/contents/docs/error-tracking/rate-limiting.mdx b/contents/docs/error-tracking/rate-limiting.mdx index d5639cdc0ffa..1bba027c540d 100644 --- a/contents/docs/error-tracking/rate-limiting.mdx +++ b/contents/docs/error-tracking/rate-limiting.mdx @@ -12,15 +12,18 @@ PostHog applies rate limits using a token bucket. You set a **maximum number of Because dropped exceptions are never ingested, they don't count toward your bill. -{/* SCREENSHOT: rate limiting overview / how the token bucket caps volume */} - -There are two types of rate limit. They're applied independently, and you can use either or both. +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. -{/* SCREENSHOT: project-wide rate limit settings + volume chart */} + ### Per-issue rate limit @@ -28,13 +31,16 @@ This limit applies to each issue individually. Once an issue exceeds the configu Use this to stop a single noisy issue from drowning out everything else. The per-issue limit is checked before the project-wide limit, so a runaway issue is dropped against its own bucket instead of draining your whole project budget on the way out. -{/* SCREENSHOT: per-issue rate limit settings with issue list + volume preview */} - -## Configuring rate limits +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. -You can configure rate limits in the [error tracking configuration page](https://app.posthog.com/error_tracking/configuration#selectedSetting=error-tracking-rate-limits). + -{/* SCREENSHOT: rate limits configuration section */} +## Configuring rate limits The following options are available for each limit: @@ -43,10 +49,6 @@ The following options are available for each limit: | **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. | -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. - -{/* SCREENSHOT: per-issue volume preview chart */} - 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). From f3e9d87acbf127cbf37d9bd66375a00ce8a3d1ac Mon Sep 17 00:00:00 2001 From: ablaszkiewicz Date: Sun, 7 Jun 2026 18:57:01 +0200 Subject: [PATCH 3/6] feat: improve copy --- contents/docs/error-tracking/rate-limiting.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/contents/docs/error-tracking/rate-limiting.mdx b/contents/docs/error-tracking/rate-limiting.mdx index 1bba027c540d..8a2e5fb45925 100644 --- a/contents/docs/error-tracking/rate-limiting.mdx +++ b/contents/docs/error-tracking/rate-limiting.mdx @@ -27,9 +27,7 @@ This limit applies across your entire project, regardless of which issue an exce ### Per-issue rate limit -This limit applies to each issue individually. 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. The per-issue limit is checked before the project-wide limit, so a runaway issue is dropped against its own bucket instead of draining your whole project budget on the way out. +This limit applies to each issue individually. 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. From c45042df8c511d0acfa4f047bde81be207d4809e Mon Sep 17 00:00:00 2001 From: ablaszkiewicz Date: Sun, 7 Jun 2026 18:57:41 +0200 Subject: [PATCH 4/6] docs: clarify per-issue rate limit applies to every issue automatically Co-Authored-By: Claude Opus 4.8 --- contents/docs/error-tracking/rate-limiting.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contents/docs/error-tracking/rate-limiting.mdx b/contents/docs/error-tracking/rate-limiting.mdx index 8a2e5fb45925..4b0a8974e52b 100644 --- a/contents/docs/error-tracking/rate-limiting.mdx +++ b/contents/docs/error-tracking/rate-limiting.mdx @@ -27,7 +27,7 @@ This limit applies across your entire project, regardless of which issue an exce ### Per-issue rate limit -This limit applies to each issue individually. 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. +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. From 82ac5756b1fc78a149d11147112691dfddcc5219 Mon Sep 17 00:00:00 2001 From: ablaszkiewicz Date: Sun, 7 Jun 2026 20:39:59 +0200 Subject: [PATCH 5/6] docs: rename rate limiting page and nav entry to "Rate limiting" Co-Authored-By: Claude Opus 4.8 --- contents/docs/error-tracking/rate-limiting.mdx | 2 +- src/navs/index.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/contents/docs/error-tracking/rate-limiting.mdx b/contents/docs/error-tracking/rate-limiting.mdx index 4b0a8974e52b..ce659b48418f 100644 --- a/contents/docs/error-tracking/rate-limiting.mdx +++ b/contents/docs/error-tracking/rate-limiting.mdx @@ -1,5 +1,5 @@ --- -title: Rate limit exception ingestion +title: Rate limiting --- import { CalloutBox } from 'components/Docs/CalloutBox' diff --git a/src/navs/index.js b/src/navs/index.js index e1aec4ce72a5..05f867c462f4 100644 --- a/src/navs/index.js +++ b/src/navs/index.js @@ -5051,7 +5051,7 @@ export const docsMenu = { featured: true, }, { - name: 'Rate limit ingestion', + name: 'Rate limiting', url: '/docs/error-tracking/rate-limiting', icon: 'IconThrottle', color: 'orange', From 08d43340d5d0ef5d631ad904310e72ef61c28572 Mon Sep 17 00:00:00 2001 From: ablaszkiewicz Date: Sun, 7 Jun 2026 20:42:54 +0200 Subject: [PATCH 6/6] docs: fix Vale lint (en dashes, Error Tracking capitalization) Co-Authored-By: Claude Opus 4.8 --- contents/docs/error-tracking/capture.mdx | 2 +- contents/docs/error-tracking/rate-limiting.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/contents/docs/error-tracking/capture.mdx b/contents/docs/error-tracking/capture.mdx index 1184bd626840..c5b3725a514b 100644 --- a/contents/docs/error-tracking/capture.mdx +++ b/contents/docs/error-tracking/capture.mdx @@ -455,7 +455,7 @@ import BurstProtection from './_snippets/burst-protection.mdx' -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). +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 diff --git a/contents/docs/error-tracking/rate-limiting.mdx b/contents/docs/error-tracking/rate-limiting.mdx index ce659b48418f..08dd5c6f9c61 100644 --- a/contents/docs/error-tracking/rate-limiting.mdx +++ b/contents/docs/error-tracking/rate-limiting.mdx @@ -4,7 +4,7 @@ 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). +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 @@ -12,7 +12,7 @@ PostHog applies rate limits using a token bucket. You set a **maximum number of 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). +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 @@ -27,7 +27,7 @@ This limit applies across your entire project, regardless of which issue an exce ### 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. +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. @@ -45,10 +45,10 @@ 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. | +| **Per** | The time window the limit applies over – 15 minutes, 30 minutes, or 1 hour. | -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). +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).