Skip to main content

​
Rate-limit and cooldown collector

Orbit’s request boundary has one job: decide whether a request should run now, later, or never. It answers that with a taxonomy of buckets — each with its own scope, its own cap, its own retry posture — rather than a single “slow down” gate. When you read a 429 as “one of these named buckets fired,” a rejected request stops being noise and becomes a handle-able signal. This page collects the API-request limiters into one model and names the cooldown classes that pace sends and recipients, so you know which layer fired and which lever moves it. (Sibling page Rate-limit and cooldown taxonomy covers the message- and verify-level 429 families — frequency caps, recipient cooldowns, Meta’s WhatsApp tiers; here the scope is the request boundary itself.)

​
Why traffic classes exist

Rate-limit buckets aren’t only an absolute-abuse defense. Orbit paces traffic on per-channel, per-credential, and per-recipient tiers as well: sender-warming states that ramp a new number gradually, per-API-key windows so one noisy integration throttles only itself, and cooldowns that protect a recipient or a route-family. Each bucket answers a different question — the platform ceiling, a tenant’s shared quota, a single key’s leak-containment, a provider’s inbound flood — and the response headers name the one that fired.

​
The taxonomy table

Every bucket has four attributes: the scope it isolates (tenant, key, route family, or recipient), the guarantee it gives (an HTTP 429 plus the response header naming the bucket), the idempotency pair so the retry never double-charges, and a retry posture that tells your client when it is safe to come back. Billing tiers feed the global cap: your plan’s requestsPerSecond ceiling (Starter 50, Growth 100, Business 500, Enterprise 1000) is the starter-tier safety net that sits under every endpoint; per-route buckets then tighten or loosen it. When a route doesn’t declare one of these named buckets, the boundary falls back to the plan ceiling. A global safety net like this is the foundation — the route buckets are what you triage against. For the message- and verify-level family tree (frequency caps you create, per-recipient cooldown counters, Meta/WhatsApp tier caps) see Rate-limit and cooldown taxonomy. For the retry contract itself see Idempotency and safe retries.

​
Where it’s enforced

Enforcement lives in one place: the route boundary config passed to the API’s rate-limit plugin. When a bucket fires the limiter runs at the route’s preHandler (before auth completes), so the guarantee — HTTP 429 with a Retry-After header and a retry_after body field — travels with the rejection. Route families map onto the buckets above consistently: auth-read and auth-write on the CRUD surface (messages, numbers, verify, contacts), money on anything that moves credits (top-ups, refunds, purchases), agent-invoke on any LLM-fronted call, and the webhook-inbound lane pairing a high per-IP ceiling with a per-tenant gate after tenant resolution so one tenant’s inbound burst never exhausts another’s. An inline max/timeWindow config that bypasses the named buckets still emits a custom:<max>/<window> label — observability kept either way.

​
Cooldown classes

A cooldown is a deliberate “not yet” that resets on its own clock — different from a rate window that refills on a cadence and different from a hard block. Orbit’s request boundary leans on three of them: Each class is tenant-owned and defaults open, in line with Orbit’s compliance posture: the platform owns only the US TCPA federal voice dialing-window guard — everything else is a control you hold, not a gate Orbit imposes.

​
Operator levers

You move these, not us:
  • Per-key rate limits and quotas — set each API key’s own per-minute window and monthly request quota in the console so one noisy integration trips its own 429 without spending a sibling key’s budget. See API rate limits console.
  • Usage and telemetry dashboards — the operational sentinels surface charts the request boundary’s counters and buckets so you can see a bucket firing before a client reports it. See Operational sentinels and Insights dashboards.

​
Failure model

When a request exceeds a bucket the response is 429 Too Many Requests with a Retry-After header and a retry_after body field. Rate-limit overage itself is not billed — only requests the platform actually processes (sends, invocations, lookups) consume credits. Safe retry works because of the idempotency pair: every write and money endpoint expects an Idempotency-Key header, and every webhook event carries a dedup key. Replaying the same payload under the same key after a 429 collapses to the original — the platform never double-charges you for your own backoff. For inbound webhooks a 429 is a healthy rate-limiter responding to a provider flood, not a dropped event — the provider retries and the per-tenant gate scopes the blast to one tenant. For full retry semantics see Idempotency and safe retries, and for 429 handling mechanics see Rate limits.

​
See also