Quotas & Alerts

Combined reference for usage quota enforcement and billing, and the alerts and webhooks system.

Quota Management

The quota system controls how much each workspace can use across tenants and subscribers within a billing period. It uses counted operations (requests, connections) as the primary billing unit — not bytes. One accepted write is one unit; one accepted read is one unit. This makes usage predictable and easy to explain.

Byte tracking (request/response sizes, payload spikes) continues for abuse detection, observability, and capacity planning, but bytes are not the commercial quota unit.

Key Concepts

• Workspace — the billing entity. All quota enforcement and invoicing is scoped to a workspace. In current terminology a workspace maps to company ownership.
• Tenant — a product or environment under a workspace. Tenants contribute usage to their parent workspace's quota.
• Subscriber workspace — a separate workspace that consumes read-only access to another workspace's tenant. Subscriber reads are billed to the subscriber's workspace, never the publishing tenant's workspace.
• Billing period — a fixed window (start and end date) tied to a workspace's subscription. Usage counters reset at each rollover.
• Quota mode — the behavior applied when included usage is exhausted (see Enforcement Modes in 5.1).

Separation from Rate Limiting

Quota enforcement and rate limiting are separate systems that solve different problems:

A request can pass rate limiting but be denied by quota (hard stop), or be throttled by rate limiting while the workspace still has quota remaining. Both systems run independently.

• 5.1 Billing & Policies
• 5.2 Enforcement & Summaries
• 5.3 Usage Rollup

Alerts and Webhooks

Alerts fire when game key or tenant API key traffic exceeds a configured threshold within a rolling time window. They are recorded in bus_alerts and trigger emails, in-app notifications, and webhook deliveries to any registered endpoints. Alerts are notification-only — they do not throttle or block requests.

There are two alert types:

Both types apply to both key kinds:

Game auth key alerts apply to requests that successfully resolve an X-Game-Key, including tenant-scoped player authentication routes such as POST /api/player-auth/email/otc and POST /api/player-auth/otc/exchange. Player auth flows that do not use X-Game-Key, such as global player portal OTC routes, are not game-key alert subjects.

Data Model

Tables:

• bus_alert_settings — platform-wide alert thresholds and suppression window

• bus_alerts — alert records (rate_spike, payload_spike)

• bus_alert_webhooks — webhook registrations (platform or tenant scope)

• bus_alert_webhook_deliveries — queued webhook deliveries and retry state

• 5.4 Alert Detection & Settings

• 5.5 Webhooks & Delivery