Repository navigation
[FEATURE]:Native API Key Pool & Automatic Failover to Prevent Rate Limit Task Failures #42502
Description
Problem
Currently, OpenCode only supports a single API key per model provider. When that key hits a rate limit (HTTP 429), runs into a server error (500), or exhausts daily quota, any active agent task stops immediately with no way to recover automatically.
For long, complex coding tasks, this is very disruptive — you lose progress mid-work and have to manually restart the session, which defeats the purpose of an autonomous coding agent. There's no built-in way to work around rate limits short of manually swapping keys, which breaks the native workflow.
I know issue #7602 covers model-level fallback, but this request focuses specifically on key-level pooling and failover within the same provider/model, which is a more targeted fix for everyday rate limit issues.
Proposed Solution
Add a native API key pool manager directly at the LLM adapter layer, with these core capabilities:
- Multi-key rotation: Let users configure a list of multiple API keys for the same provider, with round-robin distribution to spread out request load.
- Instant failover: Automatically retry requests that return 429 or 500 status codes with a different key from the pool, so the agent loop continues without interruption.
- Smart cooldown: Temporarily remove throttled keys from rotation for a short window (default 60s, or following the
Retry-Afterresponse header if provided). - Quota tracking: Automatically disable keys that hit their daily quota limit until midnight UTC reset, with an option for manual re-enablement.
- TUI status display: Show real-time key status (active / cooling down / quota exhausted) directly in the terminal interface for transparency.
Additional Notes
Separately, I think there are other worthwhile efficiency improvements for OpenCode — like better prompt caching via context diffing, a tree-sitter based repo map to reduce context bloat, and per-step reasoning effort controls. I've focused this issue on key pooling since it's the most immediate reliability problem for me, but I can open separate, focused issues for those other ideas if there's interest.
Activity
github-actions commentedon Aug 14, 2026
This issue doesn't fully meet our contributing guidelines.
What needs to be fixed:
[FEATURE]:has no description after the colon. Please give the issue a meaningful title summarizing your request.Please edit this issue to address the above within 2 hours, or it will be automatically closed.
This issue might be a duplicate of existing issues. Please check:
If you believe this was flagged incorrectly, please let a maintainer know.
my-txz commentedon Aug 14, 2026
done
github-actions commentedon Aug 14, 2026
Thanks for updating the issue — the description is much better now and reads clearly in your own words.
However, the issue title is still just
[FEATURE]:with nothing after it. Please add a short, descriptive title summarizing your request, for example:[FEATURE]: API key pool manager with rotation and failover.Once the title is updated, this issue will be fully compliant.
[-][FEATURE]:[/-][+][FEATURE]:Native API Key Pool & Automatic Failover to Prevent Rate Limit Task Failures[/+]my-txz commentedon Aug 14, 2026
done
github-actions commentedon Aug 14, 2026
Thanks for updating the issue — it looks great now. The title is clear and the description explains the problem and proposed solution well. We appreciate you taking the time to fix it!
github-actions commentedon Oct 15, 2026
To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.