Claude API stop_reason=refusal Billing: Zero-Cost Early Refusals and Advisor max_tokens Cap

Anthropic's Claude platform shipped two changes on June 2 that most operators have not yet absorbed. Neither is a model release. Neither announced itself on social media. But taken together they hand operators two new cost-and-latency levers that were not available a week ago — and both are live in production right now.

What changed

Zero-cost early refusals

When a streaming classifier intervenes before Claude generates any output, the API now returns stop_reason: "refusal" with a billable-token count of zero. The relevant line from the release notes:

On the Claude API, you are no longer billed for a request when it returns stop_reason: "refusal" without Claude having generated any output.

There is a critical boundary: if Claude does produce output tokens before the refusal fires, the full request is still billed. The zero-charge only applies when the safety classifier intercepts the request before any generation happens.

Advisor tool max_tokens parameter

The advisor tool — the beta feature that lets a lower-cost executor model consult a higher-intelligence advisor mid-generation — now accepts a max_tokens parameter that caps how many tokens the advisor model can produce per call. From the release notes:

The advisor tool now supports a max_tokens parameter to cap the advisor model's output per call, reducing latency and output token cost for workloads that don't need full-length advisor responses.

Without this cap, advisor calls routinely consumed 400–700 text tokens plus 1,400–1,800 thinking tokens per invocation. Operators can now tighten that ceiling for workloads where a shorter plan is sufficient.

Why it matters

Refusal billing removes a cost penalty from safety

Before June 2, every refusal — even the early ones triggered before a single token was generated — still incurred a billed request. For operators running content-moderated workloads at scale, this created a perverse cost incentive: turn off safety layers to avoid paying for empty responses.

The new policy aligns safety with economics. Early refusals are now free, which means there is no longer a direct financial penalty for keeping content classifiers enabled. For multi-tenant API platforms, this is the kind of invisible policy change that shifts the math on whether to enforce guardrails at the gateway level or trust provider-side safety.

The key implementation detail: you need to distinguish between early refusals (zero-cost) and mid-generation refusals (still billed). If your cost-tracking pipeline treats all refusal stop reasons the same, you will overcount charges. Update your billing logic to check whether output tokens were produced.

Advisor token cap opens a new latency tuning dimension

The advisor tool solves a specific problem: get an expensive model's plan without paying for an expensive model's full generation. But before this change, every advisor call consumed the model's natural output length — sometimes 700+ tokens of strategy text when all the executor needed was a 200-token directional nudge.

The max_tokens cap turns the advisor into a tunable knob:

• Tight cap (200–300 tokens): Fast advisory "hints" for mechanical workloads. Lower latency, lower cost, but less context for the executor.
• Medium cap (500–600 tokens): Balanced guidance for multi-step coding tasks.
• No cap (default): Full-length advisor plans for complex reasoning pipelines where every detail matters.

This is the same kind of control operators already have on the primary max_tokens parameter, now applied to the advisor sub-call. If your routing layer programmatically configures advisor invocations, the token cap is a new per-request parameter you should expose.

What to watch

Refusal cost tracking needs updating

If you run a cost dashboard that tracks Claude API spend, verify that your refusal-handling logic distinguishes between early and mid-generation refusals. The usage object still appears in early-refusal responses, but the tokens are informational only — you should not bill against them.

stop_details now ships refusal categories

The same release made the stop_details field public. When stop_reason is "refusal", stop_details returns a category (either "cyber", "bio", or null) and a human-readable explanation. This gives operators a structured signal for routing refusals to different downstream handlers — for example, retrying with a different model when the refusal category is null (content-policy) versus escalating when the category is "cyber" or "bio" (safety-critical).

Advisor tool remains beta

The advisor tool still requires the advisor-tool-2026-03-01 beta header. It is available on the Claude API and Claude Platform on AWS, but not on Bedrock, Vertex AI, or Microsoft Foundry. If your routing layer abstracts across providers, advisor token capping only applies to direct Claude API calls.

What TheRouter users should do

If your routing policy includes Claude as a provider, these two changes are worth auditing:

1. Refusal billing: Confirm your cost-reconciliation pipeline accounts for the new zero-cost early refusals. If you are routing through an API gateway, check whether the gateway's billing layer already handles this or needs a patch.
2. Advisor token cap: If you use the advisor tool through direct Claude API calls, expose tools[].max_tokens as a configurable parameter in your routing config. This is a direct latency-and-cost optimization knob that did not exist before June 2.

Both changes are live now. No migration is required — they are additive, not breaking. But ignoring them means leaving cost and latency on the table.