Free-tier quota is IP-bucketed, not account-bucketed: pre-exhausted shared IPs block users on their very first request #60991

Description

Summary

OpenCode’s free-tier quota is enforced per egress IP address, not per user account (confirmed by maintainers in #9611 and visible in the codebase via the IpRateLimitTable). This design has a severe, documented consequence: any user sharing an egress IP with one or more other OpenCode users inherits their consumed quota before sending a single message.

This means a free user can open OpenCode for the first time in a day, send one trivial prompt, and immediately receive:

Free usage exceeded, subscribe to Go [retrying in 20h ...]

…despite having made zero prior requests that day. This is not a rate-limit burst or a runaway agent loop—it is the quota bucket already being empty when the user arrives, because someone else on the same IP spent it.

The problem is widespread, affects VPN users, CGNAT/mobile-carrier users, corporate NAT users, and cloud-hosted users, and is compounded by additional IP-bucketing side effects (paid users still hitting free limits, escalating retry timers, and undocumented reset semantics).

1. What “IP bucketing” means and how it is confirmed

“IP bucketing” means the free-tier usage counter is keyed to the egress IP address of the request, not to the API key, session ID, or account.

Confirmation from multiple sources:

• OmniRoute documentation repeatedly states: “The opencode free tier is IP-based, not account-based (max_completion_tokens needs to be <= max_tokens - prompt_len #9611). When connections share an egress IP they share one bucket.”
• The same wording appears across OmniRoute commits and issues: “The OpenCode free tier counts usage per egress IP, not per account (max_completion_tokens needs to be <= max_tokens - prompt_len #9611). Connections leaving through the same IP share one budget.”
• The OmniRoute issue feat(app): improved layout #10880 reiterates: “Some providers bucket their free-tier quota by egress IP — the maintainer himself documented this for opencode in max_completion_tokens needs to be <= max_tokens - prompt_len #9611 (‘the opencode free tier is IP-based, not account-based’).”
• OpenCode’s own schema uses an IpRateLimitTable with dailyCount and lifetimeCount keyed by IP, and a source snippet shows the limiter throwing FreeUsageLimitError when dailyCount >= dailyLimit for that IP.
• The opencode-unlimited-proxy project explicitly describes its rotating-IP pool as working around “the per-address quota ceiling”—separate from the refusal error itself.
• Multiple community reports confirm the practical consequence: “Rate limits on free models are tied to IP address. Connecting to a VPN when you hit a limit resets it immediately.” Another: “换账户/换电脑没用，免费额度是按 IP 限制的” (“changing account/computer does nothing; the free quota is IP-limited”).

Reset timing is also IP-scoped. One source describes the free tier as allowing “200 requests a day, per exit IP, and resets at 00:00 UTC.” Another states the daily counter resets at UTC midnight (08:00 Beijing time) and is “与使用者的首次请求时间无关” (“unrelated to the user’s first request time”).

2. The core failure mode: pre-exhausted shared IP

Because the bucket is shared per IP, the state of your quota depends entirely on what other people on your IP have already done today.

2a. First-request failure (the primary symptom)

Issue #42128 documents exactly this: a user sends their first and only message (a minimal test prompt like “hai”) on DeepSeek V4 Flash Free and immediately receives Free usage exceeded on attempt #2. The issue’s “Possible Causes” section correctly identifies the mechanism: “Free-tier quota may be shared/pooled across all users and already exhausted server-side (not user-specific).”

Issue #35568 reports the same pattern: creating a brand-new OpenCode user immediately returns Free usage exceeded despite “no real consumption.”

A Chinese-language report states the conclusion directly: “换账户/换电脑没用，免费额度是按 IP 限制的，这也是为什么你新账户几分钟后照样报同样错误” — “Switching accounts or computers does nothing; the free quota is IP-limited, which is why your new account reports the same error within minutes.”

2b. Who is affected

2c. The “unlimited usage exploit” confirms the inverse

Issue #34344 (“Unlimited usage Exploit on opencode models”) is the mirror image of the same design flaw: “Rate limits on free models are tied to IP address. Connecting to a VPN when you hit a limit resets it immediately… Deepseek v4 Flash and mimo v2.5 ran continuously for weeks with no effective limit.”

The existence of this exploit is strong corroboration: if quota were account-bucketed, rotating VPNs would not reset it. The fact that it does reset proves the bucket is IP-scoped. The same mechanism that lets a malicious user evade limits is the one that lets innocent users be blocked before they start.

3. Secondary effects of IP bucketing

3a. Paid users still hit the free-tier IP limiter

Issue #33318 reports that after adding a $20 paid Zen balance, requests still return FreeUsageLimitError from the IP rate limiter. The issue hypothesizes that “the free usage limiter may still be checked before billing/account state, or the request is being classified as free/anonymous even when using a paid Zen API key.”

This means IP bucketing does not cleanly yield to paid status. A paid user on a congested/shared IP can be blocked by the free-tier quota of that IP. OmniRoute code comments also note that a plan-level 429 “cascaded ‘Shared egress IP quota exhausted’ across ALL sibling connections for days.”

3b. Retry timers escalate and do not reflect the real reset

Users report that after hitting the IP limit, switching to a different free model does not bypass the block—instead the retry countdown gets longer. Issue #50093: “Use a free Zen model until quota is hit → Wait for the stated retry window → Retry with either same model still blocked or switch models and hit the same error with a longer countdown.”

This is consistent with IP bucketing: all free models share the same IP bucket, so switching models does nothing, and retry attempts can compound the cooldown.

3c. Reset semantics are opaque and inconsistent

Sources conflict on the reset window:

• Some say UTC midnight (00:00 UTC): “200 requests a day, per exit IP, and resets at 00:00 UTC.”
• Some say a rolling 24-hour cycle, not a midnight boundary: Issue What are the specific use terms of OpenCode Zen & its models per IP address, please? #16844 asks “when the usage counter shifted from a midnight reset to a 24-hour cycle.”
• Some Chinese guides say local-time midnight: “按 IP 每天本地时间 0 点重置” (“resets per IP at local time 0:00 each day”).
• Others say Beijing time 08:00 (UTC midnight).

The inconsistency itself is a bug: users cannot predict when their IP bucket will refill, and documentation does not resolve it.

3d. Privacy and fairness implications

IP bucketing means usage is attributed to a network address, not a person. A user who has never used OpenCode can be blocked because a stranger on the same ISP NAT, VPN, or corporate network consumed the shared allowance. There is no way for an individual to prove they have not used the quota, because the counter is not tied to their identity.

4. Why this is distinct from other quota issues

This bug is specifically: the quota unit is the wrong entity (IP instead of account), so the quota can be pre-consumed by third parties before the user acts.

5. Proposed fixes (prioritized)

P0 — Stop blocking users who have not used the service

1. Bucket quota by account/session identity, with IP as a secondary concurrency guard. The canonical fix is what issue #34344 already suggests: “Tie rate limits to an account, not the IP.” Use IP only to limit concurrent requests or short-window burst rate, not to define the daily allowance.
2. If account-bucketing is impossible for anonymous/free users, provide an explicit “IP bucket status” endpoint or UI indicator showing whether the current egress IP’s daily quota is already exhausted, before the user sends a request. This does not fix fairness, but it prevents the surprise and allows the user to switch networks before wasting time.

P1 — Fix secondary effects

3. Ensure paid status overrides IP-based free-tier rejection. Issue [URGENT] Zen paid balance still hits FreeUsageLimitError / daily free usage limit. #33318 should be resolved so that a valid paid balance or API key bypasses the IP free-quota check entirely. Billing state must be evaluated before the IP limiter.
4. Stop escalating retry timers across models on the same IP. If switching models cannot help (because the bucket is IP-scoped), the UI should say so explicitly and show the IP bucket’s reset time, rather than presenting a longer countdown that implies the new model has its own independent quota.
5. Document the actual reset rule unambiguously. State whether the daily counter resets at UTC midnight, a rolling 24-hour window, or local midnight, and whether the lifetime count is also IP-scoped. Issue What are the specific use terms of OpenCode Zen & its models per IP address, please? #16844 already asks for this documentation; it should be treated as a P1 correctness issue, not a nice-to-have.

P2 — Structural and fairness improvements

6. Add a grace allowance for “first request of the day” per account. Even if the IP bucket is shared, a small per-account floor (e.g., 5–10 requests/day) would let a user confirm the service works and distinguish a personal quota issue from a shared-IP exhaustion issue. This is a harm-reduction measure, not a full fix.
7. Expose the egress IP and its bucket state in logs/diagnostics. The OmniRoute code persists egress_ip per request; OpenCode could expose the same in opencode stats or logs so users can self-diagnose whether they are on a congested IP.
8. Consider a hybrid model: per-account daily quota + per-IP concurrency/rate limit. This preserves abuse protection (rate limiting prevents a single IP from flooding the service) while removing the pre-exhaustion failure mode (daily allowance is not consumed by unrelated users).

6. Immediate workarounds for affected users

7. Open questions for maintainers

1. Is the free-tier daily quota definitively IP-bucketed, and if so, what is the exact bucket definition? (Single IPv4? IPv6 /64? NAT pool? Any account component at all?)
2. What is the reset rule for the IP bucket—UTC midnight, local midnight, or rolling 24 hours? Why do sources and error messages conflict?
3. Why does a paid Zen balance still hit FreeUsageLimitError ([URGENT] Zen paid balance still hits FreeUsageLimitError / daily free usage limit. #33318)? Is the IP limiter evaluated before billing state? Can this be reordered?
4. Is the lifetime counter also IP-scoped? One source states “lifetime 计数与当日计数都按 IP 记录” (“both lifetime count and daily count are recorded per IP”). If so, a long-lived shared IP can be permanently degraded even after a daily reset.
5. What is the intended behavior for users on CGNAT, corporate NAT, or cloud platforms where a dedicated IP is impossible? Is the free tier simply unsupported on these networks, and if so, can that be stated explicitly?
6. Can the retry mechanism be changed so that a 429 on one free model does not escalate the countdown for other models when they share the same IP bucket?

Plugins

No response

OpenCode version

No response

Steps to reproduce

No response

Screenshot

No response

Operating System

No response

Terminal

No response