proxy-resilience

Proxy Resilience

Overview

A corporate proxy fronting Anthropic API traffic enforces its own rate limits and allowlist behavior, independent of the underlying account's tier — a 429 or connection-refused error in a proxy-fronted session is a different failure class than a direct-API rate limit (already retried natively by the harness; do not apply this convention to those).

Covers two related failure modes sharing one root cause (transient corporate-proxy unavailability) and one remedy shape (bounded backoff, a hard retry ceiling, then escalate): rate-limit errors (issue #723, this file) and connection-refused errors (issue #724). Documented together so either failure mode is found in one place.

Detection Signals

Treat an error as proxy rate-limiting when it shows all of:

1. The session is known to run against a corporate proxy (e.g. the anthropic-proxy operating note, a proxy env var/base URL, or a previously observed proxy hostname in error text).
2. The error text contains HTTP 429, "rate limit", "too many requests", or "quota exceeded".
3. The error references the proxy host, not api.anthropic.com directly.

Treat an error as proxy connection-refused (#724) when it shows (1) above plus a connection-level failure (ECONNREFUSED, "connection refused", "could not connect", timeout connecting to the proxy host).

Backoff Schedule

Apply exponential backoff per call site (one place repeatedly issuing the same request — e.g. one subagent retrying one API call, not the whole session): initial delay 1s, ×2 multiplier, 60s cap, max 5 attempts.

Attempt	1	2	3	4	5 (last)
Delay	1s	2s	4s	8s	16s

After 5 retries at the same call site still fail with a proxy rate-limit error, stop retrying and escalate (below) rather than looping further. Five is deliberately far below any plausible recurrence of "28 rate-limit errors in one session" — that scale breaches this ceiling on the first call site alone, well before reaching 28.