Fix OpenCode and OpenRouter errors by first identifying where they originate: OpenCode’s model configuration, your OpenRouter credentials or account limits, or the upstream model provider. A model-not-found error, a 401 authentication failure, and a 429 rate limit need different remedies; changing keys or retrying blindly can make diagnosis harder.
Identify the error before changing settings
Check the error message, OpenCode logs, and—when available—the OpenRouter response body and headers. Classify the failure as a model reference or access issue, authentication or provider-configuration issue, or a rate-limit response. A 429 alone does not tell you whether the cause is OpenRouter’s request limits, spending or credit controls, or upstream provider throttling.
| Symptom | First checks | Likely next action |
|---|---|---|
ProviderModelNotFoundError or unavailable model |
Provider/model syntax, exact model ID, account access, and opencode models |
Correct the reference or select a model available to the account |
| Authentication failure or 401 | OpenCode connection, OpenRouter key status, network access, and whether BYOK credentials are involved | Reconnect or replace an invalid key; if using BYOK, check the upstream provider’s credentials and permissions |
| Provider initialization or configuration error | Provider configuration, logs, and OpenCode version | Correct configuration and reconnect; consider clearing local configuration only if it appears corrupted |
| 429 response | Error metadata, rate-limit headers, key/credit state, and whether the upstream provider returned the throttle | Honor retry guidance; adjust routing or fallback models if the issue is provider capacity |
Fix model-not-found and unavailable-model errors
OpenCode documents model references in the form <providerId>/<modelId>. Its example is openrouter/google/gemini-2.5-flash. Check both parts of your configured model name against the current OpenRouter model catalog; a model name saved in configuration does not guarantee that the current account can use it. OpenCode’s troubleshooting guidance says that ProviderModelNotFoundError most likely means a model is being referenced incorrectly. See OpenCode troubleshooting and the OpenRouter OpenCode integration guide.
- In OpenCode, run
opencode modelsand inspect the available model entries. - Compare the provider and model identifier in your configuration with the exact ID in OpenRouter’s model catalog.
- In the OpenCode TUI, use
/modelsto browse and select a model, as described in OpenRouter’s integration guide. - If the identifier is correct but the model remains unavailable, check whether your OpenRouter account has access to it and choose an accessible model if needed.
Resolve OpenRouter authentication and 401 failures
For an OpenRouter connection managed through OpenCode, open the TUI, enter /connect, choose OpenRouter, and provide a valid API key. Verify that the key remains active and that your network can reach the provider API. OpenRouter documents API key authentication and recommends protecting credentials; use its API authentication documentation for key details.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall#1 Best Overall
Do not confuse an OpenRouter key with a provider’s own key. If you configured a provider’s credentials through BYOK (“bring your own key”), OpenRouter may be able to receive the request while the upstream provider rejects it. Check that provider’s key, permissions, and provider-side status separately. The OpenRouter BYOK guidance covers upstream credentials and throttling.
Diagnose provider initialization and configuration errors
When the error appears to happen before a model request succeeds, review OpenCode’s provider configuration and capture logs with opencode --print-logs. Check the error output, compare your setup with the provider instructions, and update OpenCode with opencode upgrade if appropriate. The OpenCode troubleshooting page also documents clearing stored configuration and reconnecting as a later recovery step for invalid or corrupted configuration.
Review the logs and confirm the correct provider setup before clearing stored state. Reconnecting may help with stale credentials, but it will not correct a wrong model ID or an upstream provider’s rejected BYOK key.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Understand and recover from OpenRouter 429 rate limits
Use the 429 response details to distinguish among OpenRouter request limits, spending or credit controls, and upstream provider throttling. When returned, inspect error.metadata.limit_source, X-RateLimit-* headers, and Retry-After. OpenRouter’s API Credit & Rate Limits documentation describes these mechanisms; thresholds can be dynamic, so do not assume a fixed request allowance from another setup or date.
Quick Recap
- If a retry hint is present: wait at least as long as
Retry-Afterspecifies. For transient throttling without a usable hint, retry with exponential backoff rather than in a tight loop. - If metadata points to spending or credits: inspect the key and account’s credit or spending status. OpenRouter’s key endpoint can report key and credit information; consult its limits documentation for the current details.
- If the upstream provider is throttling: allow broader provider routing or configure fallback models where your setup supports them. Repeated immediate retries are unlikely to resolve a provider-capacity problem.
Use a safe recovery order
- Record the exact error and inspect OpenCode logs with
opencode --print-logs. - Check the configured provider/model reference and account access with
opencode models. - For a 401, reconnect with
/connectand verify the relevant OpenRouter or BYOK key. - For a 429, inspect response metadata and headers, then follow the retry hint or address the identified account or provider limit.
- Only after checking configuration and logs, consider the documented clear-configuration-and-reconnect recovery for suspected corrupted OpenCode state.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
