> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate-limit and cooldown taxonomy: which limiter fired when a send returns 429

> The complete map of Orbit's limiter families — per-API-key request caps, tenant throughput ceilings, frequency caps, per-recipient cooldowns and anti-pumping gates, and per-channel provider caps — what each one protects, the error code it raises, and how to honor retry_after.

# 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](/guides/rate-limits); for the pre-send gate chain a send
walks see
[Outbound send gating](/concepts/send-gating-and-quiet-hours); for
troubleshooting steps on a live 429 see
[Troubleshooting: cooldown and rate-limit 429s](/troubleshooting/rate-limits).

## 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.

| Limiter                     | Scope                                                                  | Error code            |
| --------------------------- | ---------------------------------------------------------------------- | --------------------- |
| Per-endpoint `RATE_LIMITED` | Per API key, per endpoint — e.g. `POST /messages/sms` 100/min          | `RATE_LIMITED`        |
| Global ceiling              | 50 requests/sec across every endpoint on the key, rejected immediately | `RATE_LIMITED`        |
| Verify global               | Per-minute request cap on `POST /verify/start`                         | `RATE_LIMIT_EXCEEDED` |

Every 429 in this family returns a `retry_after` field (seconds) and a
`Retry-After` header. Details and per-endpoint limits:
[Rate limits](/guides/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.

| Limiter                        | Scope & toggle                                                                           | Error code                                               |
| ------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| Per-org concurrency (voice)    | `organizations.voice_max_concurrent` — organization cap                                  | `CONCURRENCY_LIMIT_EXCEEDED`                             |
| Per-messaging-service MPS      | Operator-set per-messaging-service ceiling                                               | `MESSAGING_SERVICE_MPS_EXCEEDED`                         |
| Per-number MPS                 | Operator-set per-DID hard ceiling                                                        | `NUMBER_MPS_EXCEEDED`                                    |
| Per-country voice window       | Per-destination-country sliding window (voice fraud guard)                               | `VOICE_COUNTRY_RATE_LIMITED`                             |
| Customer SIP trunk             | CPS + concurrent caps on a customer trunk                                                | `VOICE_TRUNK_CPS_CEILING` / `VOICE_TRUNK_CONCURRENT_CAP` |
| WhatsApp messaging tier (Meta) | Meta's per-tier daily recipient ceiling; backpressure so a burst doesn't breach the tier | `WHATSAPP_TIER_LIMIT_EXCEEDED`                           |

<Note>
  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.
</Note>

## 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](/guides/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.

| Error code                            | Limiter                                                                    | Fires on                                                          |
| ------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `VERIFY_RESEND_COOLDOWN`              | Per-recipient OTP re-send cooldown                                         | Recipient asked for a new OTP before the resend cooldown elapsed  |
| `VERIFY_RECIPIENT_RATE_LIMITED`       | Per-recipient OTP send-rate gate (anti-SMS-pumping / anti-harassment)      | Recipient hit the per-recipient send-rate limit                   |
| `VERIFY_FRAUD_BLOCKED`                | Tenant's Verify fraud-guard policy (geo / operator risk / composite score) | Destination flagged by the tenant's anti-fraud policy             |
| `SMS_BLOCKED_DESTINATION`             | Platform destination blocklist (premium / pumped routes)                   | Destination prefix on the blocklist                               |
| `FRAUD_BLOCKED`                       | Tenant/blocklist pre-send fraud gate                                       | General pre-send fraud check on that recipient                    |
| `WHATSAPP_MARKETING_FREQUENCY_CAPPED` | Meta's per-recipient marketing frequency cap                               | A MARKETING template blocked to keep ecosystem engagement healthy |

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).

## 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](/compliance/send-gates) for the tenant-ownership split, and
[Send gates](/concepts/send-gating-and-quiet-hours) 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

* [Troubleshooting: cooldown and rate-limit 429s](/troubleshooting/rate-limits) — live steps on an active 429
* [Rate limits](/guides/rate-limits) — per-endpoint API request tables and retry patterns
* [Outbound send gating](/concepts/send-gating-and-quiet-hours) — the admission chain a send walks before dispatch
* [Frequency caps](/guides/frequency-caps) — create and tune frequency-cap rules
* [SMS-pumping protection](/guides/sms-pumping-protection) — scoring destination risk before you send
* [Error codes reference](/reference/error-codes) — the full error catalog and response shapes
* [Send gates](/compliance/send-gates) — tenant-owned compliance controls
* [Verification lifecycle](/concepts/verification-lifecycle) — the Verify state machine the cooldown codes gate
* [WhatsApp channel](/channels/whatsapp) — Meta tier caps and quality posture