Set one — there is no default
A new project’s cap is null. Nothing is capped until billing.cap.set is called, so it belongs at the start of setup rather than the end.
The value is whole cents for the calendar month. Passing null removes it.
What happens at the cap
A send or broadcast that would take the live environment past the cap is refused with spending_cap_reached and HTTP 402. Nothing is queued — the refusal happens before the message is written.
The error’s fix names the way out: raise or remove the cap with billing.cap.set, or wait for the next month. An agent holding the 402 does not have to be told what to do next.
Two sends racing at the limit cannot both slip through: the check takes a per-project lock first.
What it does not cover
The cap covers metered sends — emails and SMS segments. Monthly active users are billed monthly and cannot be refused, so they are outside it.
It applies to the live environment. Test mode does not spend.
billing.cap.get reports the cap, the month’s spend so far, what remains, and whether the cap is currently enforced — with a reason when it is not.Last modified on September 13, 2026
