Skip to main content

​
Troubleshoot squad and conversation cost caps

Two 429 codes gate LLM spend inside the AI-agent envelope, one level below the org-wide spend ceilings. SQUAD_DAILY_CAP_REACHED fires on a squad whose today-so-far LLM spend meets its own daily cap; CONVERSATION_COST_CAP_REACHED fires when one conversation burns through the agent’s per-conversation cap. Both are tenant-owned ceilings you set, and both clear without touching the wallet. This page answers: which envelope tripped, how to read the cap vs reset it, and what a supervisor does while the envelope is blocked.
The org-level daily and campaign ceilings (SMS_DAILY_SPEND_CAP, CHANNEL_DAILY_SPEND_CAP, VOICE_DAILY_SPEND_CAP, CAMPAIGN_VOICE_SPEND_CAP_REACHED) live on spend-cap refusals. The squad and conversation codes on this page gate only agent LLM cost; the org envelope still wraps them.

​
The enforcement codes

Both codes are 429 refusals on the agent invocation path. No model call fires once the envelope trips, and nothing is billed beyond what the conversation or squad already spent. The squad 429 is a deliberate stop-spending decision: the routing layer refuses before calling the fallback agent again, so the refusal surfaces as a structured error to the inbound caller instead of silently burning the fallback’s budget.

​
Read the cap vs reset it

Squad daily cap. GET /api/v1/agents/squads/:id returns the squad row with its max_cost_per_day_cents ceiling; compare it against the error’s current_cents / cap_cents detail fields to see how far over (or under) the squad ran. To clear the refusal before UTC midnight:
  • Raise the ceiling — PATCH /api/v1/agents/squads/:id with a larger max_cost_per_day_cents.
  • Remove the ceiling — set max_cost_per_day_cents: null (no squad cap; per-agent and org envelopes still apply).
Per-conversation cap. The counter lives on the conversation id, not the agent — reusing the same conversation id keeps failing no matter what you change on the agent row. Two tenant operations clear it:
  • Start a new conversation — post the next turn with a fresh conversation id.
  • Delete the conversation — the counter resets, and a subsequent turn on a new id starts at zero.
Raising max_cost_per_conversation_cents on the agent unblocks new conversations; the blocked one still terminates on its own counter.
A per-agent max_cost_per_conversation_cents above the platform hard cap (DEVOTEL_LLM_PER_CONVERSATION_MAX_USD, default $5) is silently clamped — the enforced ceiling can be lower than the value you configured. Check the precedence chain on cost controls before assuming a raise took effect.

​
What a supervisor does while the envelope is blocked

Each unblock path is a tenant-owned operation — pick one, then re-point the traffic:
  1. Raise the squad cap (above). The squad resumes routing immediately; no traffic has to move.
  2. Deflect to a fallback queue. Point the inbound entry (the classifier agent deployed on your channel) at a handoff target — a human queue or a generalist fallback agent not in the squad — until UTC midnight rolls the squad window. Handoff targets are configured per agent from handoff targets.
  3. For a conversation cap, route the blocked user’s next turn through a new conversation id (new conversation, clean budget) and leave the capped thread’s history readable on the old id.
Do not blind-retry either 429. The squad cap re-evaluates only at UTC midnight or after a raise; the conversation cap never re-evaluates — a retry loop burns your queue and trips rate guards on top.

​
Isolate the envelope

Squad caps sit on top of the per-agent cost controls, and the per-agent envelope still resolves underneath cost controls. When a squad blocks at its daily cap while individual members each look healthy, the squad window is the envelope that tripped — raising max_cost_per_conversation_cents on a member does not lift it. Cross-check one refusal against the envelope the response names before changing ceilings.

​
When to escalate

Escalate when the refusal persists after the unblock operation for that code. Include:
  • Your tenant ID (GET /api/v1/me → organizationId).
  • The exact code (SQUAD_DAILY_CAP_REACHED or CONVERSATION_COST_CAP_REACHED) and one request ID.
  • For a squad cap: the squad ID, current max_cost_per_day_cents, and the error’s current_cents / cap_cents detail.
  • For a conversation cap: the agent ID, the blocked conversation ID, and the resolved cap value.

​
See also

  • Spend-cap refusals — the org-wide channel/daily/campaign ceilings that wrap the agent envelope.
  • Cost controls — per-run, per-conversation, token, and tool-iteration ceilings, and the precedence chain that resolves the per-conversation cap.
  • Agent squads — squad composition, fallback semantics, and the max_cost_per_day_cents field.
  • Error codes reference — the canonical list of every enforcement code.