Skip to content
Cost & Performance Intermediate

Budget Cap Behavior

Understand how --max-budget-usd works: checked between turns, not mid-generation

Command

"color:#9CA3AF;font-style:italic"># This $0.001 budget will be overshot:
$ "color:#7C5CFC">claude -p "Write a detailed essay" "color:#d97757">--output-format json "color:#d97757">--max-budget-usd 0.001
  
"color:#9CA3AF;font-style:italic"># Result: $0.152 actual spend (152x overshoot!)

Response

{
  "subtype": "error_max_budget_usd",
  "is_error": false,
  "total_cost_usd": 0.152,
  "result": "",
  "modelUsage": {
    "claude-opus-4-6": { "outputTokens": 5446, "costUSD": 0.152 }
  }
}

Parsing Code

059669">">const data = JSON.parse(output);
059669">">if (data.subtype === 059669059669">">'error_max_budget_usd') {
  059669">">// Controlled stop, not a crash (is_error: false)
  059669">">console.warn(059669">`Budget exceeded: $${data.total_cost_usd}`);
  // result may be empty — the turn that exceeded was the last
}

Gotchas

! A $0.001 budget can result in $0.15 actual spend — budget is checked BETWEEN turns, not mid-generation
! Minimum Opus call is ~$0.016 due to system prompt overhead — setting budget below this always fails

Related Recipes

Set a Budget Cap Track Cost Per Call