> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot squad and conversation cost caps (SQUAD_DAILY_CAP_REACHED, CONVERSATION_COST_CAP_REACHED)

> An agent squad stopped routing at its daily LLM cost cap, or a conversation terminated at its per-conversation cap — read the ceiling, raise or reset it, and deflect to a fallback queue as tenant-owned operations.

# 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.**

<Note>
  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](/troubleshooting/spend-caps-hit). The squad and conversation codes on this page gate only agent LLM cost; the org envelope still wraps them.
</Note>

## 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.

| Code                            | Envelope gated                                                                                                               | Where the ceiling is set                                                                                                                                                       | Reset behaviour                                                                                                                                     |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SQUAD_DAILY_CAP_REACHED`       | The squad's whole LLM envelope — classifier + every member + fallback — summed against `max_cost_per_day_cents` per UTC day. | The squad row's `max_cost_per_day_cents` (`POST/PATCH /api/v1/agents/squads`), or **Agents → Squads** in the dashboard. `null` disables the cap.                               | Resets at UTC midnight. Raise or clear the cap to resume immediately; otherwise routing stops until the window rolls.                               |
| `CONVERSATION_COST_CAP_REACHED` | One conversation — every run touching the same conversation id — summed against the agent's resolved per-conversation cap.   | `max_cost_per_conversation_cents` on the agent config, resolved through the per-agent → org/env → platform-hard-cap chain described on [cost controls](/agents/cost-controls). | **Never resets on its own.** The counter is cleared only by deleting the conversation; a new conversation (a fresh conversation id) starts at zero. |

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.

<Warning>
  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](/agents/cost-controls#which-cap-participates-in-the-orgenv-precedence-chain) before assuming a raise took effect.
</Warning>

## 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](/agents/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](/agents/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](/troubleshooting/spend-caps-hit) — the org-wide channel/daily/campaign ceilings that wrap the agent envelope.
* [Cost controls](/agents/cost-controls) — per-run, per-conversation, token, and tool-iteration ceilings, and the precedence chain that resolves the per-conversation cap.
* [Agent squads](/agents/squads) — squad composition, fallback semantics, and the `max_cost_per_day_cents` field.
* [Error codes reference](/reference/error-codes) — the canonical list of every enforcement code.