opus-ratelimit-fanout-retry-on-sonnet-throttled-waves

Opus rate-limit on a fan-out → retry on Sonnet, throttled into waves

Problem

A wide parallel fan-out (Workflow parallel()/pipeline() or many concurrent Agent calls) launched on Opus mass-fails with a server-side capacity throttle, not your account quota. The whole fan-out collapses to a handful of results — only the agents that happened to finish before the burst survive.

Context / Trigger Conditions

• Failure string (one per dead agent): API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited → HTTP 429.
• The "(not your usage limit)" clause is the tell: this is Anthropic-side Opus capacity throttling, NOT your per-account rate limit. Waiting and retrying on Opus alone often re-hits it.
• You launched many subagents at once (one parallel() over 20–50 items, or a single message with dozens of Agent calls). The wider the simultaneous burst, the worse.
• Distinct from the empty-StructuredOutput loop (that's a schema-payload failure under the same storm — see the companion skill workflow-schema-agents-empty-loop-under-ratelimit). This skill is about the mass-429 capacity failure mode and the cheapest recovery.

Solution

Two independent levers; apply both on the retry:

1. Move the fan-out agents to Sonnet. Set model: 'sonnet' on the agent() calls (Workflow) or model: "sonnet" on the Agent tool. Sonnet draws from a separate capacity pool, so it does not contend for the throttled Opus capacity. Keep the orchestrator and the final synthesis/judge on Opus — only the fan-out workers move. Triage / review / code-tracing / classification fan-outs are well within Sonnet's range.

2. Throttle the burst into sequential waves. Instead of one N-wide parallel(), loop in chunks of ~8 (parallel within a wave, barrier between waves). This spaces the request bursts so you never present 50 simultaneous requests again:

   const CHUNK = 8
   const results = []
   for (let i = 0; i < ITEMS.length; i += CHUNK) {
     const slice = ITEMS.slice(i, i + CHUNK)
     log(`wave ${i/CHUNK+1}: ${slice.join(', ')}`)
     const r = await parallel(slice.map((it) => () =>
       agent(prompt(it), { model: 'sonnet', schema: SCHEMA })))
     results.push(...r)
   }