Skip to main content

Why this proxy works

Designed to keep your Claude API requests stable, fast, and frustration-free without unnecessary request rewriting.

Auto Retry
Claude Proxy Mascot (inspecting)

Auto Retry

Converts 403/400/504 rate-limit errors into 429 + Retry-After so the client retries automatically via its watchdog.

Clock

Retry-After Headers

Sets standards-compatible Retry-After headers on converted responses. The client applies its own exponential backoff with jitter.

403 to 429
Claude Proxy Mascot (inspecting)

403 -> 429

Detects quota-related 403 responses (including Chinese error messages like 用户额度不足) and converts them to 429. Genuine permission denials stay 403.

Terminal

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.

Safe Defaults

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.

Auto Retry

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.

Auto Retry

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.

Safe Defaults

data:null Filtering

Removes 'data: null' SSE events that break Anthropic parsers and cause silent failures in long sessions.

Safe Defaults

Local First

Runs locally on localhost:8787. Pure Python 3.8+ standard library, zero dependencies. Your API keys never leave your machine.

Safe Defaults

Circuit Breaker

Permanent errors (invalid key, model not found, permission denied) pass through without conversion, preventing infinite retry loops.

Request Lifecycle Comparison

WITHOUT CLAUDE PROXY
Request403 Org Quota ExceededSession Breaks

Your CLI request fails abruptly. You have to wait manually and rerun your command, interrupting your session state.

WITH CLAUDE PROXY
RequestProxy InterceptConvert to 429 (Retry-After)Success ✓

The proxy standardizes temporary quota errors into 429 Retry-After headers so your client auto-retries naturally without breaking session state.

$python retry-proxy.py --start --upstream https://agentrouter.org
Open source•MIT License•Zero dependencies