Skip to main content

​
Per-channel rate overrides

Every dedicated send endpoint — SMS, WhatsApp, email, RCS, Viber, Messenger, LINE, Telegram, Kakao, Zalo, WeChat, fax, and group MMS — is rate-limited per minute. Until now one cluster-wide cap applied to every tenant equally: an account whose contract allows a higher envelope hit the same ceiling as a fresh trial. Per-channel rate overrides are the escape hatch. You set a tenant-scoped cap on the channels you need, and the send path applies your cap instead of the cluster default on every dedicated send. Channels you don’t set an override for keep the cluster default. The endpoint is GET / PUT /api/v1/settings/compliance/channel-rate-overrides. Reads are open to any authenticated member of your organization; writes are restricted to owners. Full request and response shapes are in the settings API reference.

​
What an override is — and is not

An override is a per-minute envelope cap the API enforces on your account’s dedicated sends for one channel. It is a throughput control, not an abuse control: it decides how many messages per minute the API accepts for dispatch, not whether a send passes fraud, consent, or quiet-hours gates. Those run unchanged on top of whatever cap is in effect. Setting an override raises or lowers the API-side envelope only. It does not change carrier-side throughput, and it does not grant headroom the platform has not approved.

​
The override map

Both endpoints revolve around one sparse map keyed by channel. Only channel keys the platform serves are honored: sms, whatsapp, email, rcs, viber, messenger, line, telegram, kakao, zalo, wechat, fax, mms. Unknown keys are dropped, values are positive integers, and fractional values are floored. GET returns your map alongside the cluster-wide defaults and the hard ceiling, so you can always see the full picture in one response: PUT replaces the whole map — it is not a per-channel patch. Send the complete map you want active. Channels you omit from the body revert to the cluster default; channels you include must be integers between 1 and 60000 (send 422 outside that range).
To revert everything to cluster defaults, PUT an empty map: {"overrides": {}}.

​
Safety behavior

Two deliberate fail-safes protect you from your own typo and from platform trouble:
  • Sanity ceiling. Any override above 60000 per minute is dropped and the channel falls back to the cluster default. An extra zero pasted into a settings payload cannot silently unbounded your envelope — it just reverts.
  • Fail-open on read errors. If the settings lookup fails transiently, both the endpoint and the send path fall back to the cluster defaults. Sends are never 500’d because an override record couldn’t be read, and no override is ever enforced that the platform couldn’t verify against the ceiling.
A write also invalidates the cached caps immediately, so a new override applies to the very next send — you don’t wait out a cache TTL for it to take effect.

​
Three caps, three purposes

Three tenant-visible rate controls sound alike but govern different things. Don’t conflate them: Rule of thumb: rate overrides answer “how fast may my legitimate traffic go?” Fraud caps answer “how much damage can an anomaly do before it’s cut off?” Neither replaces the other, and both are enforced — a send must pass the fraud guards and fit within the effective rate cap.

​
When to set an override

Set one when all of these hold:
  • A dedicated high-throughput sender you run (a verified sender identity, a queue-draining batch worker) is hitting 429s on the cluster default.
  • Your contract and sender registration support the higher rate — for messaging channels, the carrier-side tier you hold actually allows the envelope you’re asking for.
  • You want the headroom on specific channels, not account-wide.
Stay on cluster defaults when you’re unsure, when the sends are bursty rather than sustained, or when no approved tier backs the higher number. An override above what your sender registration supports will still be throttled downstream — you only move the API envelope.
Setting an override does not promise granted throughput headroom Orbit hasn’t approved for your account. Treat the ceiling as the API-side cap, not a carrier guarantee.

​
Verify an override took effect

A three-step loop:
  1. Set. PUT the override map (owner role).
  2. Read back. GET /api/v1/settings/compliance/channel-rate-overrides and confirm the channel appears in overrides with your value. Writes invalidate the send-path cache, so the read-back value is the one enforcement sees.
  3. Confirm on the send path. Send on the channel and watch the API accept up to your cap per minute. Previously the same burst would have 429’d at the cluster default.
Every override write is recorded in your audit log with the resulting map and channel count, so the change itself is part of the trail.

​
Dashboard

The same control is available under Settings → Compliance in the dashboard: each channel’s cluster default is shown next to your override input, with the sanity ceiling beside it. Owners see the write action; other members see the current effective caps. Reads and writes on this surface are tenant-scoped — you only ever see and change your own organization’s envelope.