xhigh effort errors on Opus 4.6 and earlier

The failure

effort: "xhigh" works fine against the newer Opus models and errors immediately against Opus 4.6 or earlier. If your code sets effort based on a task-difficulty heuristic rather than a hardcoded per-model value, this is the kind of error that only shows up once that heuristic actually reaches for the top of the range — which can mean it ships clean and then fails weeks later on the first genuinely hard task that triggers it.

Why the older models don't have this level at all

xhigh isn't a renamed or repositioned version of an effort level the older Opus models already had — it's new capability that shipped with Opus 4.7, sitting between the previous top level and a level added specifically for the hardest coding and agentic work. Opus 4.6 and earlier simply don't have anywhere for that setting to go; there's no equivalent to fall back to internally, which is why the request is rejected outright rather than silently downgraded to the older model's actual maximum.

Where this hides

The dangerous version of this bug is conditional: a heuristic, an eval harness, or a difficulty classifier that only reaches for xhigh on a subset of inputs. That means testing against typical traffic can look completely clean, and the failure only surfaces once a harder input arrives in production and the code path that requests the top effort level finally runs for the first time. Anything that dynamically selects effort level is worth testing against its actual ceiling case, not just its typical one.

The fix

Cap the requested effort level per model rather than assuming the same maximum applies everywhere — on Opus 4.6 and earlier, the ceiling is one level lower than on 4.7 and later. If your logic picks effort level dynamically, clamp it against what the target model id actually supports before sending the request. See what actually changed from Opus 4.6 to Opus 5 for the rest of what moved in the same generation.