Skip to main content

​
Troubleshooting: number warming caps

A brand-new US/CA 10DLC number cannot send at full volume on day one. Carriers have no delivery history for a fresh sender, so Orbit enforces a warming ramp on the number’s behalf: a per-day send ceiling that grows as the number proves out. When your send crosses today’s ceiling, the API refuses it before any carrier is attempted and returns a 429 with one of the warming codes below. This page tells you which gate fired, how to watch the ramp advance, and what to do besides retrying.

​
Number warming vs. email IP warmup

These are two separate ramps that share one reputation principle:
  • Number warming (this page) ramps SMS/MMS volume per phone number. It applies to newly acquired 10DLC long codes and resets at midnight UTC per number. Definitions: Warmup (Number and Sender Registration).
  • Email IP warmup ramps email volume per sending IP/domain and is enforced by the email deliverability API (GET /api/v1/email/warmup-plan, /warmup-status). Definition: IP Warmup in the glossary.
A 429 on an SMS send is never the email warmup — check which channel refused before tuning the wrong ramp.

​
The three gates and their codes

Three distinct 429 codes guard a warming number. They stack: a send can clear one gate and trip the next. DAILY_CAP_EXCEEDED and WARMING_QUOTA_EXCEEDED are per-day gates keyed on one sender — wait for midnight UTC or switch senders. NUMBER_MPS_EXCEEDED is a per-second gate — a one-second backoff clears it. Do not confuse them: retrying a daily-cap 429 every second burns your queue without clearing anything. Generic cooldown and throughput 429s from other surfaces are covered on Troubleshooting: cooldown and rate-limit 429s.

​
How to observe warming progress

Two read-only endpoints expose exactly where a number stands. Both are pure reads of locally persisted state — no live carrier call. Current warming state:
Returns the current daily_cap, the live current_day_count (sourced from the pre-send gate’s counter, so it reflects sends as they happen, not an overnight snapshot), the warming_phase (initial | ramp | steady | verified), trust_score, and days_warmed. Non-10DLC numbers return null — there is nothing to warm. Growth-curve forecast:
Returns the number’s warming lifecycle state (off | warming | warmed), the mirrored warming_max_daily_sms ceiling, the live day count, and a 15-day forecast of how the daily ceiling grows — enough to render a progression chart or plan a campaign launch date without a per-day round-trip. Field reference and response shapes: Number health, warming, and carrier reputation tracking.

​
Fix paths

Work these in order; the first one that fits is the right answer.
  1. Stay under today’s cap. Read daily_cap versus current_day_count on the warming endpoint and pace your sender so the day never crosses the cap. The ramp advances on its own clock — initial → ramp → steady → verified — and each phase step raises the cap.
  2. Spread traffic over more numbers. If your real volume exceeds what one warming number allows, add senders and let several numbers warm in parallel. Warming is per-number, so a fleet ramps faster than one number ever will.
  3. Do not retry-loop within the same day. A warming 429 carries retry_after pointing at the next UTC midnight. That is a reset hint, not a backoff schedule — retrying every few seconds re-trips the gate, counts nothing new, and can trip the per-second gate on top. Queue the overflow for the next window or for a warmed sender.
  4. Leave dangerous overrides alone. Do not try to raise a single number’s cap to outrun the ramp — the daily cap is derived from the phase and trust score, and forcing volume past carrier guidance is how fresh numbers earn spam flags. An operator can set a cap to 0 to disable a number, not to accelerate it.

​
When warming completes — and when to escalate

Warming completes when the progression endpoint reports warmed (lifecycle) and the warming endpoint settles into the verified phase with a high trust_score. From then on, the daily-cap gate no longer constrains the number; only the per-second throughput gate and your tenant-level limits apply. A typical progression reaches warmed inside about two weeks of steady, accepted traffic. Escalate to support when:
  • a number stays in the same warming_phase for more than 10 days with no last_phase_advance_at movement, or
  • the phase advances but the daily cap does not rise with it, or
  • warming_state flips back from warmed to warming.
Include the number id, the output of both warming endpoints above, and the 429 code you are hitting.
A warming 429 is the ramp working, not an outage. Retry against the next UTC day or re-route to a warmed sender; a retry loop on the same number never clears a daily gate.