Repository navigation
[FEATURE]: Warn users before free tier quota exhaustion instead of silent 429 #42765
Description
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: 1786800000When 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 -vzen 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
github-actions commentedon Aug 15, 2026
This issue does not fully meet our contributing guidelines.
What needs to be fixed:
[FEATURE]:for feature requests (e.g.,[FEATURE]: Warn users before free tier quota exhaustion instead of silent 429)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.
[-]feat: warn users before free tier quota exhaustion instead of silent 429[/-][+][FEATURE]: Warn users before free tier quota exhaustion instead of silent 429[/+]github-actions commentedon Aug 15, 2026
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.
github-actions commentedon Aug 15, 2026
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!
omatheusmesmo commentedon Oct 13, 2026
+1
opencodejr commentedon Oct 28, 2026
Thanks for the detailed proposal, @thumb2086! Your request is that the Zen API sends a low-quota signal before the free-tier limit runs out, for example
X-RateLimit-Remaining/X-RateLimit-Resetheaders returned only below a threshold. Clients could then warn you ahead of time instead of hitting a suddenFreeUsageLimitError(429). Maintainers will consider it.This needs a change on the Zen server, so it can't be done with a plugin today: the API doesn't currently return any remaining-quota information for a client or plugin to read.
Related issues:
FreeUsageLimitErrorunexpectedly.