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

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.