Skip to main content

​
Rate-limit and cooldown taxonomy

A 429 on Orbit is never a generic “slow down” — it is one of several deliberate protective gates saying no at a specific scope. Some limiters guard the platform (API request ceilings), some guard your sender reputation (frequency caps, per-number MPS), and some guard the recipient (cooldowns, anti-pumping / anti-harassment gates). Each family has its own error codes, its own retry posture, and its own place in the send pipeline — and the response names the family through the error code. Read the code first; the fix for a code-frozen recipient gate is the opposite of the fix for a throughput ceiling. This page maps the four limiter families and the error codes in each, so “which limiter is firing” is one page, not a hunt across three. For the per-endpoint API tables see Rate limits; for the pre-send gate chain a send walks see Outbound send gating; for troubleshooting steps on a live 429 see Troubleshooting: cooldown and rate-limit 429s.

​
Family 1 — API request rate limits (how fast you call endpoints)

Every API key is bounded per endpoint, plus one platform-wide ceiling. These limits protect the API surface — they fire how many requests you made, regardless of how many recipients those requests touched. Every 429 in this family returns a retry_after field (seconds) and a Retry-After header. Details and per-endpoint limits: Rate limits.

​
Family 2 — Tenant throughput ceilings (how fast you dispatch)

Throughput ceilings cap the send rate — per organization, per messaging service, and per number. They exist to keep your traffic inside what the carrier/provider for that lane will accept. All of them return Retry-After: 1 (the counter resets each second) — except Meta’s WhatsApp tier, which returns a code that tells you to slow sustainably.
Unlike the rest of this family, the WhatsApp tier limiter is not a “retry in 1 second” throttle — it is Meta’s daily-recipient ceiling. Honor the response and slow the campaign; hammering past it degrades the WABA’s messaging_limit_tier.

​
Family 3 — Frequency caps (how much one contact receives in N seconds)

A frequency cap is a rule you created: “no more than N sends of this kind to this contact inside a rolling window.” It protects the recipient’s patience and your sender reputation, and it fires on over-messaging, not on duplicates. Frequency caps default off — create them deliberately.
  • Direct API / SDK sends return a 429 with FREQUENCY_CAP_EXCEEDED (or the shared RATE_LIMIT_EXCEEDED code that the messaging/verify/DSAR/ number-pool limiters reuse).
  • Campaign sends skip the capped recipient with reason frequency_capped — the batch keeps moving.
Create, inspect, and tune in Frequency caps.

​
Family 4 — Per-recipient cooldowns and anti-abuse gates (one recipient only)

These gates apply to one recipient number, not to your tenant’s batch. Two of them are Verify-specific; the rest are the messaging pipeline or Meta-side protections. They exist so a loop, an attacker, or a buggy integration cannot burn down a single subscriber. The Verify cooldown codes have direct handling consequences — see the Verify cooldowns section under What each family tells the client.

​
What each family tells the client

Read the code first. Every 429 carries a code that names the family; do not retry blindly against any 429 and do not treat them all the same. Family 1 and Family 2 (API + throughput) — retry fast. Honor retry_after / Retry-After, back off, and spread your traffic. These reset quickly. For Family 2 on a WhatsApp tier, retry slower — a tier ceiling does not reset in one second. Family 3 (frequency caps) — skip the capped recipient this window, or adjust the cap you set. Campaign sends skip the capped recipient automatically (status: "skipped", reason frequency_capped); the rest of the batch continues. Family 4 (recipient gates) — fix the loop or treat the recipient as blocked. Do not retry the same recipient in a tight loop; per-recipient cooldowns exist precisely so a loop cannot pass. If one recipient repeatedly trips VERIFY_RECIPIENT_RATE_LIMITED, check for a resend loop before asking for a limit change. Verify cooldowns — handling order. On a VERIFY_RESEND_COOLDOWN return a per-recipient countdown in your UI and do not retry until it elapses. On a VERIFY_RECIPIENT_RATE_LIMITED, back off sends to that recipient and check for a re-send loop. Both are scoped to one recipient; siblings in the same batch are unaffected.

​
Who owns each control (compliance posture)

Every limiter here is a tenant-owned control. Orbit carries the settings and evaluates them at send time; the platform owns only one hard compliance gate (the US TCPA federal voice dialing-window guard), which is unrelated to rate limiting. Throughput ceilings toggle on configured limits, frequency caps configure on rules you create, recipient cooldowns are measured per-recipient counters, and channel-specific caps come from your provider posture. See Compliance for the tenant-ownership split, and Send gates for how the gates compose into one admission model. A throughput ceiling and a frequency cap answer different questions, and a cooldown and a tier cap resolve on different clocks. Know which family is firing and you stop fixing the wrong thing.

​
See also