OpenCode Free Limit Reached: Reset, Wait, or Keep Working

When OpenCode shows Free limit reached or HTTP 429, do not immediately assume that every free model resets at a fixed daily time. Preserve the original error, confirm the active provider and model, and use only a reset hint that actually appears in the current response or account.

If no trustworthy reset time exists, choose between waiting, selecting another model that is currently available in /models, or explicitly moving to an independently billed provider. Before resuming a long coding task, send one small, non-destructive request and verify the response, the selected provider/model, and the provider-side usage.

Choose the right branch from the symptom

What you see	Likely branch	First action
Free limit reached, or a body containing FreeUsageLimitError, with no countdown	Free-tier limit	Do not invent a cycle; record the time, then wait or inspect currently available models in /models
Go limit reached with an actual countdown	OpenCode Go paid-usage window	Follow the time shown for that account; do not apply it to free models
Generic 429, Too Many Requests, or Provider is overloaded	Provider rate limit, capacity issue, or transient failure	Keep the raw response, confirm provider/model, retry later, and check provider status
401, 404, or Model not available	Authentication, Base URL, or Model ID problem	Do not wait for a reset; fix credentials, endpoint, or model configuration

The same HTTP status can have different causes. A 429 can represent a free-tier cap, an ordinary provider rate limit, or temporary overload, so the status code alone is not a reason to buy a plan or rewrite your configuration.

First, save four pieces of evidence

Before changing anything, record:

1. The complete error text, not just “429.”
2. The selected provider and model, preferably in providerId/modelId form.
3. Any visible response body, error type, response headers, and retry-after value.
4. The failure time and time zone, the project directory, and whether you were using free Zen, Go, or a custom provider.

Following the OpenCode Zen documentation, run /models in the TUI to confirm the selected entry and the models that are listed now. You can also run opencode models in a terminal to inspect models available to the current setup. Do not rely on an old screenshot or tutorial to decide that a particular free model still exists; model availability changes.

Also check configuration precedence. The OpenCode configuration documentation explains that OpenCode merges configuration from several locations, and a project-level opencode.json can override global settings. “I selected model A globally” does not prove that the current repository is using model A. Trust the current project, the /models selection, and the resolved configuration.

Use only a reset time that actually exists

If the current error does not include a reliable countdown or absolute time, do not infer “a few hours,” “tomorrow,” or “next week.”

In the OpenCode dev-branch retry.ts snapshot opened and reviewed on 2026-10-10, FreeUsageLimitError enters a static free-limit upsell branch, while GoUsageLimitError reads the retry-after response header and formats a countdown. This is a source-code snapshot check, not a runtime test of your installed version or account.

Public feature requests #53252 and #52894 have included example reset times, but those numbers are illustrations in requests, not observed free-tier schedules. An issue being closed is also not enough to prove that a change reached the client version you run.

The OpenCode Go documentation opened on 2026-10-10 separately defines 5-hour, weekly, and monthly windows for its paid usage. Those Go rules cannot be projected onto free-model resets.

Use this rule:

• A countdown or absolute time is displayed: save the exact text, time zone, and provider, then schedule one retry around that time.
• No reset time is displayed: treat the reset time as unknown. Avoid rapid repeated retries and do not substitute a window from another plan.
• Only a generic 429 is displayed: investigate provider throttling or overload until the evidence identifies a free-tier limit.

Option 1: wait when you need the same free model

Waiting is the simplest choice when the task is not urgent, you do not want separate API usage, and the error clearly points to a free-tier cap.

1. Record the last failure time and raw error.
2. Stop continuous retries so a quota problem is not mixed with transient throttling.
3. If the message contains a reliable timer, retry around that time. If it does not, check again at an interval you can tolerate without claiming a fixed schedule.
4. Test with a short request before resuming a task that reads or edits many files.

Success is not “OpenCode launched” or “the process exited with code 0.” The chosen model must return a real response without immediately repeating the original error.

Option 2: select another model currently shown in /models

If you need to keep working but do not require the original model, select another entry that is currently visible to your account and accessible through the intended provider.

Before switching, verify that:

• the model appears in the current list rather than only in an old guide;
• the entry belongs to the expected provider, so a model change does not silently become an account or billing change;
• the model is suitable for the task, which you can check with a small tool-use or code-understanding request before allowing repository edits.

A model switch is not a guarantee. Another free model may have its own cap, regional restrictions, temporary removal, or capacity problems. The defensible instruction is “select a currently available model and verify it,” not “switching free models always restores access.”

Option 3: explicitly use an independently billed provider

Use this path when the task has a deadline, you accept separate API usage, and you want requests to stop depending on the Zen free allowance. This does not reset the free quota; it routes later requests through a different account, credential, and usage record.

The OpenCode provider documentation supports custom OpenAI-compatible providers. The minimum flow is:

1. Run /connect, choose Other, enter a unique provider ID, and save the API Key in the credential prompt.
2. Configure the same provider ID, the correct Base URL, and the actual Model ID in opencode.json, then save the file.
3. Fully exit OpenCode and restart it in the same project before checking the new configuration; do not assume an already-running TUI hot-reloads a newly added provider. If you need the previous task context, note the project directory and the task or session you must return to, then re-enter it safely after restart using the workflow available in your environment.
4. After restart, run /models, confirm that the new entry appears, and select the exact providerId/modelId rather than relying only on its display name.
5. Send a small request that explicitly must not edit files, and confirm that you receive a real new model response.
6. Inspect the target provider’s request log, usage record, or balance change to verify that it actually handled this request. If no corresponding record is available, do not claim that the switch was verified.

BetterToken is one optional provider for this independent route. Its OpenCode setup documentation, opened on 2026-10-10, specifies the Base URL https://www.bettertoken.ai/v1 and a model reference such as bettertoken/YOUR_MODEL_ID. Do not append /chat/completions to the Base URL, and make sure the top-level model exactly matches the real ID declared under models.

The boundary matters: BetterToken does not supply Zen free allowance or reset an OpenCode/Zen limit. It cannot promise that every request will avoid 429, and it is not automatically cheaper without a like-for-like usage comparison. It is simply an explicit, separate API route.

Verify recovery with one small request

Use the same acceptance test after waiting, changing models, or changing providers:

1. Reconfirm the selected provider/model in the interface.
2. Send a request that asks only for the single word READY and explicitly says not to edit files.
3. Save the response and time. Make sure it is a new model response, not merely a configuration acknowledgement or cached output.
4. For an independent provider, check its usage record, request log, or balance for the corresponding small change. If the provider exposes no such evidence, do not claim that billing was verified.
5. Confirm that the original error does not recur, then return to the real task and run its smallest meaningful step first.

A valid pass combines a real response, the expected provider/model, and provider-side usage evidence. A parsed config file, a successful client launch, or a clean exit code is not enough on its own.

If the small request still fails

Follow the new error branch instead of repeating every fix:

• The same Free limit reached appears: the allowance may not have returned, or the selection did not actually change. Recheck /models and project-level configuration.
• A 401 appears: verify that the credential exists for that provider. Run opencode auth list and reconnect with /connect if needed.
• A 404 or Model not available appears: verify the Base URL, Model ID, and providerId/modelId, then run opencode models to see what is currently accessible.
• A generic 429 or overload message appears: handle it as provider throttling, reduce retry frequency, and inspect provider status instead of treating it as a Zen free-limit problem.
• The error is incomplete: use the OpenCode troubleshooting guide to inspect logs, then report the timestamp, provider, model, status, and a redacted response body.

Never paste an API Key into an issue, screenshot, or chat. Keep the useful error data, but remove authorization headers, tokens, and other credentials.

Frequently asked questions

Does the OpenCode free allowance reset at a fixed time every day?

There is no reliable first-party basis for assuming that every free model shares one daily, weekly, or monthly reset schedule. Use the time shown by the current request; if no time is shown, treat it as unknown.

Does every 429 mean the free allowance is exhausted?

No. A 429 may also be an ordinary provider rate limit, concurrency limit, or overload condition. Interpret it together with the provider, model, response body, and error type.

Is subscribing to OpenCode Go the only way to continue?

No. You can wait, choose another model that is currently available, or explicitly use an independent provider. Go is a separate paid plan, and its windows are not evidence of a free-model reset schedule.

Will switching to BetterToken clear the free limit?

No. It is an independent provider route with its own API Key, Base URL, Model ID, and usage accounting. It does not change the state of the Zen free allowance.

The practical rule

Do not solve Free limit reached by guessing a reset cycle. Identify the provider/model, trust only a real reset hint, and choose the least disruptive path that fits the deadline: wait, select a model currently available in /models, or explicitly use an independently billed provider. Prove recovery with a small response and provider-side usage before returning to the original task.