Skip to content

[FEATURE]: Cooldown-aware runtime failover on rate limits and temporary provider failures #16867

Closed as not planned
Closed as not planned
[FEATURE]: Cooldown-aware runtime failover on rate limits and temporary provider failures#16867
Assignees
kitlangton

Description

@young5lee
young5lee
opened on Mar 10, 2026

Feature hasn't been suggested before.

  • I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

  • I have searched existing issues and could not find the same request.
  • This is a feature request, not a bug report.
  • I am opening this issue first for design discussion before any PR.

Problem

OpenCode supports many providers and models, but when a configured model/provider hits a runtime failure such as:

  • HTTP 429
  • quota exhausted
  • temporary provider unavailability
  • transient timeout

the session may stop instead of trying another configured option.

That interrupts workflows even when the user has other valid providers or models configured.

Proposed solution

Please consider an opt-in, cooldown-aware runtime failover mechanism.

A possible direction:

  • classify retryable runtime failures such as rate limit, quota exhaustion, temporary unavailable, timeout
  • put the failing credential/profile/model into cooldown for a short period
  • retry with another configured profile, model, or provider
  • surface the failover decision clearly in logs / UI
  • cap retries to avoid loops

Expected behavior

If the primary model fails with a retryable runtime error:

  1. mark it temporarily unavailable
  2. try the next configured option
  3. continue the session if another option succeeds
  4. show which fallback was used and why

Why this would help

This would improve:

  • resilience
  • workflow continuity
  • cost/performance routing
  • practical multi-provider usage

Important constraint

This should be explicit and user-configured. I am not asking for silent quota bypassing. I am asking for legitimate failover across user-configured providers / models / profiles.

Additional context

This seems especially useful for people who intentionally configure multiple providers so a temporary outage or 429 does not fully block the session.

Activity

  1. young5lee
    added
    discussionUsed for feature requests, proposals, ideas, etc. Open discussion
    on Mar 10, 2026
  2. github-actions
    assigned
    thdxr
    on Mar 10, 2026
  3. github-actions
    added
    coreAnything pertaining to core functionality of the application (opencode server stuff)
    on Mar 10, 2026

  4. github-actions commented on Mar 10, 2026

    @github-actions
    github-actionsBot
    on Mar 10, 2026 – with GitHub Actions
    Contributor

    This issue might be a duplicate of existing issues. Please check:

    If these are distinct enough to warrant separate issues, please clarify how this differs from #16038 in particular.

  5. Amperstrand commented on Apr 14, 2026

    @Amperstrand
    Amperstrand
    on Apr 14, 2026

    In the meantime, I put together a stopgap script that probes all three providers for live quota and auto-updates opencode.json to disable dead ones until they recover.

    https://gist.github.com/Amperstrand/64d3e13dc917be7c0b7b5baac3361417

    What it does:

    • Probes OpenCode Zen, OpenAI (ChatGPT), and GitHub Copilot in parallel (~5s)
    • Detects subscription exhaustion, weekly limits, and premium quota depletion
    • Auto-updates ~/.config/opencode/opencode.json: sets disabled_providers and picks the best available model
    • 15-minute threshold: providers recovering soon stay enabled (no unnecessary toggling)
    • Re-enables providers automatically on the next run when their quota resets
    • Reads auth from ~/.local/share/opencode/auth.json — no keys in the script
    • Preserves all existing config fields

    Usage:

    opencode-usage              # check + auto-update config
opencode-usage --check      # check only, don't modify config
opencode-usage --json       # machine-readable JSON

    Underlying issue this works around: SubscriptionUsageLimitError in retry.ts falls through to the generic exhausted/unavailable match, so OpenCode retries the same dead provider indefinitely with exponential backoff up to 30s. This causes agents to spin for minutes/hours when a subscription is exhausted rather than failing fast or falling back to another provider. The one-line fix would be adding SubscriptionUsageLimitError alongside FreeUsageLimitError in the non-retryable check — but the broader cooldown-aware failover from this issue would be the proper solution.

    It would be great if OpenCode could do this automatically: detect when a provider has a known long-duration outage (subscription exhausted, weekly limit hit, monthly quota depleted) and either fail fast or fall back to another configured provider, rather than retrying indefinitely. The info needed to make these decisions is already available from the provider APIs — this script demonstrates that.

  6. thdxr
    assigned
    kitlangton
    and unassigned
    thdxr
    on Apr 26, 2026
  7. thdxr
    removed
    discussionUsed for feature requests, proposals, ideas, etc. Open discussion
    coreAnything pertaining to core functionality of the application (opencode server stuff)
    on May 3, 2026

  8. github-actions commented on Jul 4, 2026

    @github-actions
    github-actionsBot
    on Jul 4, 2026 – with GitHub Actions
    Contributor

    To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

  9. github-actions
    closed this as not plannedon Jul 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions