Feature Request
Summary
When a Claude.ai subscription (Pro/Max) usage limit is reached, Claude Code should automatically fall back to using a configured ANTHROPIC_API_KEY instead of stopping with an error.
Current Behavior
When the subscription limit is hit, Claude Code displays an error and stops. The user must manually switch to API mode (e.g., set ANTHROPIC_API_KEY and restart).
Desired Behavior
If ANTHROPIC_API_KEY is set (e.g., via env in settings.json or as an environment variable), Claude Code should automatically detect the rate limit / usage limit error and seamlessly retry the request using the API key — without interrupting the user's workflow.
Use Case
Users who have both a Claude.ai subscription and an Anthropic API key want uninterrupted usage: subscription credits are used first (cost-free), and API credits serve as a fallback when the subscription limit is exhausted.
Proposed Implementation
- Detect HTTP 429 / usage limit responses from the Claude.ai subscription endpoint
- If
ANTHROPIC_API_KEY is available in the environment, automatically retry via the direct API
- Optionally notify the user that the fallback was triggered (e.g., a status line message)
Configuration Suggestion
{
"env": {
"ANTHROPIC_API_KEY": "sk-ant-..."
},
"fallbackToApiKey": true
}This would make Claude Code truly seamless for power users who want maximum uptime without manually switching modes.
Feature Request
Summary
When a Claude.ai subscription (Pro/Max) usage limit is reached, Claude Code should automatically fall back to using a configured
ANTHROPIC_API_KEYinstead of stopping with an error.Current Behavior
When the subscription limit is hit, Claude Code displays an error and stops. The user must manually switch to API mode (e.g., set
ANTHROPIC_API_KEYand restart).Desired Behavior
If
ANTHROPIC_API_KEYis set (e.g., viaenvinsettings.jsonor as an environment variable), Claude Code should automatically detect the rate limit / usage limit error and seamlessly retry the request using the API key — without interrupting the user's workflow.Use Case
Users who have both a Claude.ai subscription and an Anthropic API key want uninterrupted usage: subscription credits are used first (cost-free), and API credits serve as a fallback when the subscription limit is exhausted.
Proposed Implementation
ANTHROPIC_API_KEYis available in the environment, automatically retry via the direct APIConfiguration Suggestion
{ "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }, "fallbackToApiKey": true }This would make Claude Code truly seamless for power users who want maximum uptime without manually switching modes.