opencode-zen rate limit (~15-20 RPM) is silent: no header, no doc, no client warning

[Cheurteenyt]

Client or integration

Codex App (the desktop Codex application, which routes its requests through the OpenCodex proxy at localhost:10100), also reproducible as a Direct HTTP/API client against https://opencode.ai/zen/v1.

Area

Provider adapter (the opencode-zen keyed provider — src/providers/registry.ts:1753), and Proxy and routing (rate-limit handling in src/lib/upstream-retry.ts, src/providers/key-failover.ts, src/lib/retry-after.ts).

Summary

When the keyed opencode-zen provider hits OpenCode's request rate limit, every call returns:

Provider error 429: Rate limit exceeded. Please try again later.

The proxy forwards this generic message verbatim, but exposes nothing that lets the user understand or plan around the limit:

• no Retry-After / X-RateLimit-* response headers are surfaced,
• no provider note documents the limit (the 200 requests / 5h note lives only on the keyless opencode-free provider at registry.ts:1773, even though both share the same base URL https://opencode.ai/zen/v1 and the same free-model roster),
• no client-side warning is shown before the wall,
• the key cooldown (KeyCooldown, src/providers/key-failover.ts:18) is not surfaced to the dashboard.

The user only discovers the limit after Codex exhausts its own retries and reports exceeded retry limit, last status: 429.

Reproduction

1. In the Codex App, select the model opencode-zen/deepseek-v4-flash-free (routed through the OpenCodex proxy).
2. Send requests at a sustained pace (≈15+ requests within a short window) from the Codex App chat.
3. Observe status: 429 with errorCode: "rate_limit_exceeded" and the upstream message above.

This is reproduced from real request logs (~/.opencodex/usage.jsonl): 629 total opencode-zen requests, 25 returned status: 429, all errorCode: "rate_limit_exceeded", all with upstreamError: "Provider error 429: Rate limit exceeded. Please try again later.".

Note: this is not the 200/5h quota of opencode-free. Evidence it is a short-window rate limit (burst), not a period quota:

• the first 429 cluster (2026-08-05 13:16:52 UTC) had 0 requests in the prior 5 minutes and only 2–8 requests in the prior 5-hour window → rules out a 200/5h quota,
• consecutive-429 gaps were 10 s, 21 s, 52 s early in a cluster → burst signature,
• busiest 60-second window across the whole log = 15 requests → consistent with a ~15–20 RPM cap on the keyed Zen tier.

Version

@bitkyc08/opencodex@2.10.2 (npm latest).

Operating system

Windows 11 (build 26100), but the behavior is provider-side and OS-independent.

Provider and model

opencode-zen / deepseek-v4-flash-free (also observed on laguna-s-2.1-free, longcat-2.0-free, mimo-v2.5-free during the same 429 bursts).

Logs or error output

status:429  model:deepseek-v4-flash-free  provider:opencode-zen
upstreamError: "Provider error 429: Rate limit exceeded. Please try again later."

Rolling 5h-window request counts just before each 429 (excerpt):
  2, 3, 4, 5, 6, 7, 8   (early cluster — nowhere near a 200/5h quota)
Busiest 60s window: 15 requests

Redacted configuration

{
  "providers": {
    "opencode-zen": {
      "apiKey": "REDACTED_OPENCODE_ZEN_API_KEY",
      "baseUrl": "https://opencode.ai/zen/v1"
    }
  }
}

Checks

• I searched existing issues and documentation. (Note: [Feature]: add per-account Gem/Cla quota display for Google Antigravity #1082 covers quota/reset display; this issue is the underlying silent 429 on opencode-zen and the missing limit metadata — a distinct root cause.)
• I removed secrets, tokens, account details, request credentials, and personal data.

[github-actions]

_{Automated translation bookkeeping — detected language: English.}

[Wibias]

Related

• [Feature]: provider/key cooldown recovery notifications #1146 — provider/key cooldown watchdog and reset notification. This issue tracks understanding and exposing the rate limit itself; [Feature]: provider/key cooldown recovery notifications #1146 tracks detecting recovery after a limit has been reached.

[Wibias]

[GD] Opened PR #1330 to address this.

[Wibias]

[GD] Research review

Claim: Keyed opencode-zen free-model traffic hits a short-window ~15–20 RPM ceiling; OpenCodex forwards opaque 429s with no usable backoff metadata or provider note.
Checked against: dev@3e5cd5374 (release/default: n/a for this tip check)

Field	Finding
Still an issue on latest development?	yes
Exact issue	opencode-zen registry entry had no rate-limit note; Zen 429 Rate limit exceeded bodies lack Retry-After / X-RateLimit-*, so clients only learn after exhausting retries
Fixed on development?	no — addressed in open PR #1330
Open PR covering this?	#1330 (fix(providers): surface OpenCode Zen short-window rate limits, @Wibias, open)
Duplicate of?	none — related follow-up #1146 (cooldown watchdog / notify-on-reset), not the same root cause
Security relevance	none — documentation + client error/backoff surfacing; no auth/credential/workflow changes
Priority	middle — real free-tier stall for Codex App users; workaround is slower pacing / other providers
Verdict	Covered by open PR

Evidence

• Tip check: src/providers/registry.ts opencode-zen lacked a rate-limit note while opencode-free only documented ~200/5h
• Tip check: Responses error path built Provider error 429: … and used resolveClientRetryAfter with the generic 2s default when Zen omitted headers
• History: documented rateLimits UI was intentionally removed in dadda3251 / feat(providers): fill rate-limit gaps in the providers overview #1157 follow-up; not reintroduced
• Repro: not re-hit live Zen RPM in this session; relied on issue log evidence + tip code paths

Gaps: Live Zen 429 reproduction not re-run here (needs a keyed Zen account and sustained traffic).

Recommended next: review/merge #1330; keep #1146 for cooldown/reset notification follow-up.