[FEATURE]: Warn users before free tier quota exhaustion instead of silent 429 · Issue #42765 · anomalyco/opencode · GitHub
Skip to content

[FEATURE]: Warn users before free tier quota exhaustion instead of silent 429 #42765

Open
Open
[FEATURE]: Warn users before free tier quota exhaustion instead of silent 429#42765
Assignees
MrMushrooooom

Description

@thumb2086
thumb2086
opened on Aug 15, 2026

Verification Checklist

  • I have searched existing issues and this is not a duplicate
  • I understand this is a feature request, not a bug report

Problem

When using free models (-free suffix) on OpenCode Zen, users hit FreeUsageLimitError (429) with no prior warning. The only feedback is a sudden "Free usage exceeded, subscribe to Go" dialog. This is especially painful for users behind shared IPs (CGNAT, corporate networks), where the quota may be exhausted by other users on the same IP.

Related issues: #15585 #42029 #42128 #33495

Proposal

Add rate-limit response headers to zen API responses so clients can display a warning when quota is running low.

Only include headers when remaining quota is below a threshold (e.g., <20% remaining). This way:

  • Users get advance notice before hitting 429
  • The exact total limit is never exposed
  • The official team retains full control over the numbers
HTTP/1.1 200 OK
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1786800000

When above the threshold, no headers are returned (current behavior unchanged).

Why not expose on every request?

This keeps the daily limit opaque while still solving the core UX problem: users know they're running low and can plan accordingly, without learning the exact cap.

Implementation scope

File Change
packages/console/app/src/routes/zen/util/ipRateLimiter.ts Return counts from check()
packages/console/app/src/routes/zen/util/handler.ts Write headers when remaining < threshold
packages/opencode/src/session/retry.ts Parse headers for early warning (optional)

Verification

  • curl -v zen endpoint, verify headers appear when quota is low
  • Confirm no headers when quota is high (no info leak)

Note on duplicates

This may overlap with #40588 and #41684. Happy to consolidate there instead if preferred.

Activity

  1. github-actions
    assigned
    MrMushrooooom
    on Aug 15, 2026
  2. github-actions
    added
    needs:complianceThis means the issue will auto-close after 2 hours.
    on Aug 15, 2026

  3. github-actions commented on Aug 15, 2026

    @github-actions
    github-actionsBot
    on Aug 15, 2026 – with GitHub Actions
    Contributor

    This issue does not fully meet our contributing guidelines.

    What needs to be fixed:

    • The title should start with [FEATURE]: for feature requests (e.g., [FEATURE]: Warn users before free tier quota exhaustion instead of silent 429)
    • The Feature Request template requires a verification checkbox confirming you have searched for existing issues — this is missing

    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.

  4. thumb2086
    changed the title [-]feat: warn users before free tier quota exhaustion instead of silent 429[/-] [+][FEATURE]: Warn users before free tier quota exhaustion instead of silent 429[/+] on Aug 15, 2026
  5. github-actions
    removed
    needs:complianceThis means the issue will auto-close after 2 hours.
    on Aug 15, 2026

  6. github-actions commented on Aug 15, 2026

    @github-actions
    github-actionsBot
    on Aug 15, 2026 – with GitHub Actions
    Contributor

    Thank you for updating the issue! It now meets our contributing guidelines. We appreciate you taking the time to provide a clear problem statement and a well-thought-out proposal.

  7. github-actions commented on Aug 15, 2026

    @github-actions
    github-actionsBot
    on Aug 15, 2026 – with GitHub Actions
    Contributor

    Thanks for updating the issue! It now clearly follows the feature request template with a well-described problem, proposal, and implementation scope. Everything looks good — appreciate the thorough write-up!

  8. omatheusmesmo commented on Oct 13, 2026

    @omatheusmesmo
    omatheusmesmo
    on Oct 13, 2026

    +1

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