What this error means
OpenCode Zen returns HTTP 429 with FreeUsageLimitError when a request hits the ceiling on one of its free trial models. The gateway passes the upstream provider's rate limit through, so it fires regardless of your account balance.
How to fix it
- Check whether you are calling a Zen free model rather than a paid one.
- Back off and retry with exponential delay before rotating keys.
- Switch to a paid Zen model or another provider for sustained agent load.
- Route through Manifest so the request fails over automatically.
Example error message
{
"type": "error",
"error": {
"type": "FreeUsageLimitError",
"message": "Rate limit exceeded. Please try again later."
},
"metadata": {}
}How Manifest handles it
Manifest treats FreeUsageLimitError as a routing signal and retries against the next model in your fallback chain, so a capped free model does not stop the run.
Frequently asked
Why does the official opencode CLI work when my own client gets a 429?
Users report the same key working from the official CLI but failing on direct API calls. The cause is undocumented, so avoid free Zen models in production.
More Opencode-zen errors
| Code | Error | Affected teams / 30 days | |
|---|---|---|---|
| 401 | OpenCode Zen 401: "Model is not supported" | 119 | View |
| View all Opencode-zen errors | |||
Route Opencode-zen through Manifest
Live token usage, every model, and automatic fallback when Opencode-zen rate-limits or fails.