{{ message }}
Repository navigation
Zen free models: publish the current free-usage limit and return it in 429 responses #55816
Closed as not planned
Description
What I'm asking for
Please be transparent about the Zen free-model limits. Today a client cannot tell how much free usage it has, when it resets, or why a request was refused, so a "free" model behaves like an unannounced trial.
In #28055 a maintainer said free usage is dynamic and shifts with capacity. That is reasonable, but the current value should still be visible. Concretely:
- Publish the current rule in the Zen docs: the unit (requests or tokens), the window (per hour, per 5 hours, per day, rolling or fixed), and the scope (account, API key or IP). If it changes with capacity, say so there and show the current value.
- Say why a request was refused in the 429 response with standard headers, e.g.
Retry-Afterandx-ratelimit-limit/x-ratelimit-remaining/x-ratelimit-reset, so clients can back off precisely instead of polling. - Use one error type, or document the difference. Others report
FreeUsageLimitError([URGENT] Zen paid balance still hits FreeUsageLimitError / daily free usage limit. #33318, FreeUsageLimitError persists 10+ days on deepseek-v4-flash-free even for minimal requests — while other free models work #42977). We gettype: "rate_limit_error"with the same message. Is this a separate short-term limit or the same free-usage cap?
What we observed (2026-10-15, America/Toronto)
- Model:
opencode-zen/deepseek-v4.1-flash-free, via the OpenAI-compatible completions endpoint, from a third-party agent harness. - First refusal at 14:23:55, then every retry about once a minute was refused, still at 14:57:
429: {"code":null,"message":"OpenCode Zen: Rate limit exceeded. Please try again later.","param":null,"type":"rate_limit_error"} - No
Retry-Afteror reset information was available to the client. - Our own count before the first refusal: about 966 requests on this model since 08:00, about 500 of them between 13:00 and 14:24. We can live with any limit; we just need to know what it is.
Related
#52894 and #53252 (show reset time), #54338 (reset time not exposed via API), #33318, #28055, #42977.
Activity
opencode-agent commentedon Oct 15, 2026
Thanks for the detailed write-up and the request counts. As I understand it, you're asking for three things for Zen free models: publish the current free-usage limit (unit, window and scope, even if it changes with capacity), return standard
Retry-After/x-ratelimit-*headers on 429 responses, and either use one error type or document howrate_limit_errordiffers fromFreeUsageLimitError.These are changes to the Zen service and its docs rather than to the OpenCode app, so I've marked this as a feature request for the maintainers to consider.
Related issues:
retry-after, as Go limits already doFreeUsageLimitErrorfeat: per-key request accounting and upstream signal capture
neriousy commentedon Oct 21, 2026
Thanks for the detailed write-up. Free limits change with capacity on purpose, so we don't publish a fixed number.
OpenCode Go and the free models have usage limits. They're set by plan, and for free models they also change with available capacity, so they're not something we can raise case by case. Your current usage and reset times are in the console, and how the limits work is described at https://opencode.ai/docs/go. If you think your usage was counted wrongly on your account, email help@anoma.ly with your workspace ID.