Zen free models: publish the current free-usage limit and return it in 429 responses #55816

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:

1. 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.
2. Say why a request was refused in the 429 response with standard headers, e.g. Retry-After and x-ratelimit-limit / x-ratelimit-remaining / x-ratelimit-reset, so clients can back off precisely instead of polling.
3. 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 get type: "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-After or 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.