Skip to main content

Retry Logic Smarter failure handling.

Claude Proxy automatically detects temporary failures, respects rate limits, and retries with exponential backoff — so your coding sessions stay alive.

Mascot 1Mascot 2Mascot 3Mascot 4
1
Timeout
Network
2
Capacity
529
3
Server Error
5xx
4
Quota Exceeded
403 ➔ 429

Intelligent Rate Limit Handling

Quota Exceeded
403
Converted & Retried
429
Retry-After: 12s
Session Stays Alive

We normalize 403 rate limit responses into 429 with Retry-After and retry automatically — no action needed.

Exponential Backoff

Jitter included

Exponential Backoff Curve

Randomized Jitter Included

Backoff doubles each retry attempt, capped at a maximum 16s timeout. Jitter prevents thundering herd spikes.

Backoff doubles each time, up to a safe maximum. Jitter prevents thundering herd.

What We Retry (Automatically)

Timeouts
No response in time.
Capacity Errors
529, overloaded upstream.
Server Errors
500, 502, 503, 504.
Rate Limits
403 (quota) ➔ 429

We do not retry 4xx errors other than rate limits, or client-side issues.

bash
curl http://127.0.0.1:8787/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": {
    "type": "rate_limit",
    "message": "Rate limit exceeded",
    "retry_after": 12
  }
}
Reliability by default. Productivity by design.
Open source • MIT License