OAuth expiration causes retry storm consuming 100% session usage (3.75M wasted tokens)

Bug Report: OAuth Expiration Causes Massive Usage Consumption via Retry Storm

Summary

When OAuth token expires, Claude Code retries API calls with expired credentials 19+ times, sending ~134k tokens per attempt. This burns through entire session usage quota (100%) before user realizes auth has expired. Failed authentication attempts should NOT count against usage quotas.

Environment

• Claude Code Version: 2.0.31
• Platform: Linux (Ubuntu-based, kernel 5.15.0-153-generic)
• Invocation: sudo claude (running as root)
• Session Date: 2025-10-31

Steps to Reproduce

1. Start Claude Code session with valid OAuth credentials
2. Build up conversation history (~28 messages, ~134k tokens when summarized)
3. Allow OAuth token to expire (happened naturally, unclear what triggers expiration)
4. Send new command (e.g., /secondbrain)
5. Observe usage consumption

Expected Behavior

When OAuth token expires:

1. First API call fails with 401
2. Claude Code immediately prompts user to re-login
3. No retries on authentication failures
4. Failed auth attempts do NOT count against usage quota
5. User re-authenticates and continues with minimal usage loss

Actual Behavior

When OAuth token expired:

1. First API call failed with 401 authentication error
2. Claude Code retried 19 times, each time sending ~134k tokens
3. After 401 failures exhausted session quota, hit 429 rate limit errors (9 times)
4. All failed attempts counted against usage quota
5. User consumed 100% of session usage limit before doing any actual work
6. User consumed 11% of weekly quota with zero productive output

Evidence from Debug Logs

Session Start - Massive Context Being Sent

[DEBUG] Summarizing last 10 of 28 messages (~133768 tokens)

Authentication Failures (19 occurrences)

[ERROR] Error streaming, falling back to non-streaming mode: 401 {"type":"error","error":{"type":"authentication_error","message":"OAuth token has expired. Please obtain a new token or refresh your existing token."},"request_id":"req_011CUfaNuEnLTbEdkwfrqKpk"}

Rate Limit Errors After Usage Exhausted (9 occurrences)

[ERROR] Error streaming, falling back to non-streaming mode: 429 {"type":"error","error":{"type":"rate_limit_error","message":"This request would exceed your account's rate limit. Please try again later."},"request_id":"req_011CUfh6njEBwgP1q75fLTLy"}

Usage Calculation

• Retry attempts: 19 failed 401s + 9 failed 429s = 28 failed API calls
• Tokens per attempt: ~134,000 tokens (conversation context)
• Total wasted tokens: ~3.75 million tokens sent for failed auth
• Session limit consumed: 100%
• Weekly quota consumed: 11% (with zero productive work)

Impact

• Severe: Users with expired OAuth tokens unknowingly burn entire session quota
• Financial: Wasted API costs on failed authentication attempts
• User Experience: Confusing - usage shows 100% with no apparent work done
• Trust: User believes system is broken or tracking incorrectly

Root Causes

1. Aggressive Retry Logic on Auth Failures

Claude Code retries failed requests, but doesn't distinguish between:

• Network errors (should retry)
• Auth errors (should NEVER retry - fail fast)

2. Usage Counting on Failed Auth

401 authentication errors shouldn't count against usage quotas - the API never processed the request.

3. No User Notification on Auth Expiration

User had to manually discover OAuth was expired. No proactive prompt to re-login.

Proposed Fixes

Critical (P0)

1. Fail fast on 401 errors - Do NOT retry on authentication failures
2. Prompt immediate re-login - Show user "OAuth expired, please re-login" on first 401
3. Zero usage counting for auth failures - 401 errors should not count against quotas

Important (P1)

1. Token expiration detection - Proactively check token expiration before sending large contexts
2. Rate limit on retries - Even for retryable errors, cap at 3 attempts max
3. Better error messaging - Distinguish auth failures from network errors in UI

Nice to Have (P2)

1. OAuth token refresh - Automatically refresh tokens before expiration
2. Usage dashboard accuracy - Show breakdown: successful vs failed API calls

Workaround

User had to:

1. Notice usage was inexplicably at 100%
2. Run /login to manually re-authenticate
3. Wait for session timer to expire and reset quota
4. Restart work from scratch

User Quote

"I went all the way to 100% usage. It was terrible and has still used up a lot of my weekly quota now."

Additional Context

• User runs custom /secondbrain command that loads large context (~25k tokens)
• This is a legitimate use case for context engineering
• User has never had to manually re-login before this incident
• Running as root via sudo may have affected token storage paths, but shouldn't cause retry storm

Files Available for Investigation

• Debug log: /root/.claude/debug/a38dd300-0375-42fd-ba09-f9a0c7362caf.txt (106KB)
• Session history: /root/.claude/projects/-home-jason-PycharmProjects-SecondBrain/a38dd300-0375-42fd-ba09-f9a0c7362caf.jsonl (338KB, 135 messages)
• Can provide additional logs if needed

---

This is a critical bug affecting user trust and causing real financial impact via wasted API usage.