Cap exceeded behavior

When your application sends more events in a billing period than your plan’s monthly allotment, Beacon’s behavior depends on whether your plan is cap-policy or charge-policy. This page explains both.

The cap states

Beacon tracks four monthly event-allotment states for every tenant. The state shows up as a colored badge on the Billing page (sidebar Billing, top-right of the Current Plan section):

Two additional terminal cap states exist outside the monthly-allotment flow: Cancelled (after cancellation completes) and Trial Expired (after the 21-day trial ends without conversion). Both block ingestion with 402 and recover only by starting or reactivating a subscription.

You’ll receive an email at the billing contact when a state transition happens, so the first signal usually comes via email rather than the dashboard.

Cap-policy plans — Trial and Starter

These plans don’t bill overage. When you exceed the allotment, you enter a grace window; if you don’t take action by the time it expires, ingestion stops.

Behavior:

1. Active → Soft Cap Exceeded → Grace Period Active — the first time your event count crosses the monthly allotment, the cap state transitions and an email goes out. Dashboard, reports, and SDK ingestion continue working through the grace window.
2. Grace Period Active → Hard Capped — happens when the grace window expires without the cap clearing (upgrade or new billing cycle). The API starts returning 402 for new events. Dashboard, reports, and historical data remain accessible — only new ingestion is blocked.
3. Recovery: upgrade to a charge-policy plan, wait for the next billing cycle (the allotment resets), or accept the cap.

Charge-policy plans — Pro and Business

These plans bill overage per-event instead of capping. There’s no hard cap on event volume.

Behavior is different from cap-policy: charge-policy plans stay in Active cap state even after exceeding the allotment. There’s no Soft Cap Exceeded / Grace Period transition — overage simply starts metering. You’ll see a billing-side notification (email + invoice line item) rather than a cap-state badge change. The API keeps accepting events indefinitely.

Recovery: upgrade to a tier with a larger allotment, accept the overage cost, or reduce event volume.

The Usage History on the Billing page shows period-by-period base cost vs. overage.

Enterprise

Enterprise is custom and effectively unlimited by default. Overage is 0 unless your contract specifies otherwise.

What the SDK does when ingestion is paused

When the API returns 402 (cap-policy plans only), SDK behavior differs by platform:

• .NET and C++ queue events to durable local storage and retry automatically once ingestion resumes. Best-effort retry up to the configured queue size; eviction at the cap.
• JavaScript logs the 402 and discards the events rather than persisting them. The browser SDK’s keepalive flush only handles the page-unload exit path, not durable retry across 402 responses. If your application is JS-based and you anticipate hitting cap, consider a server-side ingestion proxy with one of the desktop SDKs.

For .NET and C++ tenants: when you upgrade or the billing cycle rolls over, queued events flush automatically.

When did I exceed?

The Billing page’s Current Plan section shows your current usage with a progress bar. The Usage History section shows period-by-period breakdowns so you can see when growth started.

Common questions

The badge is yellow but my email said “soft cap exceeded yesterday.” The badge can lag by up to ~60 seconds due to caching; emails fire the moment your cap state changes. They align within a minute.

I’m on Pro — will I ever see a yellow or orange badge? No. Charge-policy plans (Pro, Business) stay Active regardless of overage; the badge stays green. The Soft Cap Exceeded / Grace Period Active / Hard Capped states only apply to cap-policy plans (Trial, Starter).

Next

→ Getting support