Why this proxy works
Designed to keep your Claude API requests stable, fast, and frustration-free without unnecessary request rewriting.
Auto Retry
Converts 403/400/504 rate-limit errors into 429 + Retry-After so the client retries automatically via its watchdog.
Retry-After Headers
Sets standards-compatible Retry-After headers on converted responses. The client applies its own exponential backoff with jitter.
403 -> 429
Detects quota-related 403 responses (including Chinese error messages like 用户额度不足) and converts them to 429. Genuine permission denials stay 403.
Header Injection
Injects the claude-cli/1.0.0 User-Agent that AgentRouter requires. Without it, AgentRouter rejects non-Claude-Code clients with 401 unauthorized.
Stream Inspection
Peeks at the first SSE events to detect errors hidden inside HTTP 200 responses. Catches 'empty or malformed response' crashes before they reach the client.
Malformed Response Fix
Detects empty bodies, HTML error pages, and JSON error payloads disguised as 200. Converts them to retryable 503 so the client retries instead of crashing.
Response Folding
When a client requests non-streaming (stream:false), the proxy folds the forced SSE stream back into a single JSON object matching the expected format.
data:null Filtering
Removes 'data: null' SSE events that break Anthropic parsers and cause silent failures in long sessions.
Local First
Runs locally on localhost:8787. Pure Python 3.8+ standard library, zero dependencies. Your API keys never leave your machine.
Circuit Breaker
Permanent errors (invalid key, model not found, permission denied) pass through without conversion, preventing infinite retry loops.
Request Lifecycle Comparison
Your CLI request fails abruptly. You have to wait manually and rerun your command, interrupting your session state.
The proxy standardizes temporary quota errors into 429 Retry-After headers so your client auto-retries naturally without breaking session state.
