Skip to main content

​
Troubleshoot spend-cap refusals

Spend-cap refusals are tenant-owned ceilings you (or the platform fraud guard) set — they differ from the wallet balance gate (INSUFFICIENT_BALANCE 402) and from warming caps on new numbers. When a send, call, or campaign launch is refused with one of the codes below, the request never leaves the platform pre-flight; nothing is dispatched and nothing is billed beyond the estimate hold. This page answers: which cap fired, where the ceiling is raised, and how to tell this apart from a balance 402 or a warming 429.
A warming cap (DAILY_CAP_EXCEEDED / WARMING_QUOTA_EXCEEDED on a fresh 10DLC number) is a carrier-side ramp gate — see number warming caps. This page covers the paid-envelope spend ceilings only.

​
The enforcement codes

Every spend-cap refusal is a 429 on the synchronous send path. Campaign voice caps also auto-pause the campaign.

​
Distinguish spend-cap refusals from balance and warming gates

Three different 4xx families stop outbound traffic. Work the descriptions against the error code returned by the API:
  • INSUFFICIENT_BALANCE (402) — the wallet pre-flight couldn’t cover the estimate hold. You are out of money on account: either top up, or let auto-top-up fund the wallet. The gateway halts before any spend ceiling is considered. See INSUFFICIENT_BALANCE (402).
  • Spend-cap 429 (this page) — the wallet was funded, but the tenant-owned daily or campaign ceiling evaluated before the send left the platform. You are out of budget room, not wallet balance: raising the ceiling (or the campaign cap on a dialer row) clears the refusal without touching wallet funds. Triggering when balance_cents reads fine is the diagnostic tell.
  • Warming cap 429 on a fresh number (DAILY_CAP_EXCEEDED / WARMING_QUOTA_EXCEEDED / NUMBER_MPS_EXCEEDED) — the carrier-side ramp on a newly acquired 10DLC sender, unrelated to balance or org ceilings. See number warming caps.

​
Worked example — agency hitting a per-campaign voice cap

You run a dialer campaign on behalf of a client with a hard spend limit. The campaign’s voice_spend_cap_cents is the campaign row’s ceiling; the dialer launches each call only after it claims against the campaign counter.
  1. Call #412 returns 429 CAMPAIGN_VOICE_SPEND_CAP_REACHED and the dialer pauses the campaign (status: paused).
  2. Read the campaign row (GET /api/v1/campaigns/:id) — the ceiling is on the campaign, not the org.
  3. Either raise voice_spend_cap_cents on the campaign (the client raised their cap), or split the remaining call list into a sister campaign (tenant-owned envelope isolation).
  4. Re-enable the campaign (PUT /api/v1/campaigns/:id with status: "active").
The same isolation principle covers a tenant that can’t raise an org-level daily-spend alert: route the overflow through a new campaign or number envelope rather than looping the same refusal.

​
Where daily spend surfaces

Three dashboard/API surfaces surface today’s spend before the refusal arrives:
  • Billing → Alerts — the spend-alert rules (daily_spend / spend_amount) you chose. When a rule trips it either notifies or pauses/blocks outbound (SENDING_PAUSED 402) — text notifications come from usage & delivery anomaly alerts on the Spend metric if configured against the wallet.
  • GET /api/v1/me header → dashboard Billing widget — the current outbound-paused flag and running balance, so operators see a cut-off org before they trip the pause code.
  • Billing → Alerts → clear the alert re-arms outbound once a pause/block alert fired and the enforced envelope is re-admitted.

​
When to escalate

Escalate when the refusal persists after you raised the ceiling on the surface the response names. Include:
  • Your tenant ID (GET /api/v1/me → organizationId).
  • The exact code and the request ID of one refused call.
  • For a campaign voice cap: the campaign ID and the current voice_spend_cap_cents ceiling.
Do not blind-retry a 429 spend refusal: unlike a warming reset it never re-evaluates until you raise the ceiling, so a retry loop burns your queue and trips the per-second rate guard on top.

​
See also