OpenCodeのFree limit reached対処法：待つ・切り替える・続ける

OpenCodeでFree limit reachedやHTTP 429が表示されても、すべての無料modelが毎日決まった時刻にresetすると決めつけないでください。まず元のerrorを保存し、現在のproviderとmodelを確認して、今回のresponseまたはaccountに実際に出ているreset情報だけを判断材料にします。

信頼できる時刻がなければ、待つ、/modelsに現在表示される別modelへ切り替える、独立課金のproviderへ明示的に移る、という3つの選択肢があります。長いcoding taskへ戻る前に、fileを変更しない小さなrequestを送り、response、選択中のprovider/model、provider側のusageを確認します。

表示された症状から分岐を選ぶ

表示	可能性が高い分岐	最初にすること
Free limit reachedまたはFreeUsageLimitError、countdownなし	無料枠のlimit	固定周期を推測せず、時刻を記録して待つか、/modelsの現在利用可能なmodelを確認する
Go limit reachedと実際のcountdown	OpenCode Goの有料usage window	そのaccountに表示された時刻だけを使い、無料modelへ当てはめない
一般的な429、Too Many Requests、Provider is overloaded	providerのrate limit、容量不足、一時障害	生のresponseを保存し、provider/modelを確認して時間を置き、provider statusを確認する
401、404、Model not available	認証、Base URL、Model IDの問題	resetを待たず、credential、endpoint、model設定を直す

同じHTTP statusでも原因は異なります。429だけでは、無料枠の消費、通常のprovider rate limit、一時的なoverloadを区別できません。そのため、status codeだけを見てplanを購入したり設定を全面的に書き換えたりしないでください。

切り替える前に4つの情報を保存する

1. 「429」だけではなく、error全文。
2. 選択中のproviderとmodel。可能ならproviderId/modelId形式。
3. 表示されているresponse body、error type、headers、retry-after。
4. 発生時刻とtime zone、project directory、無料Zen・Go・custom providerのどれを使っていたか。

OpenCode Zen documentに従い、TUIで/modelsを実行し、現在選択されているentryと今表示されるmodelを確認します。Terminalではopencode modelsも使えます。古いscreenshotやguideにmodel名があるだけで、現在も無料で利用できるとは判断できません。

Configの優先順位にも注意が必要です。OpenCode config documentによると、OpenCodeは複数のconfigをmergeし、project-levelのopencode.jsonがglobal設定をoverrideできます。Globalでmodel Aを選んだことは、現在のrepositoryでもmodel Aが使われている証明になりません。現在のproject、/modelsの選択、解決後のconfigを基準にします。

実際に表示されたresetだけを信用する

現在のerrorに信頼できるcountdownまたは絶対時刻がなければ、「数時間後」「明日」「来週」と推測しないでください。

このguideで2026-10-10に開いて確認したOpenCode dev branchのretry.ts snapshotでは、FreeUsageLimitErrorは静的な無料limit通知のbranchに入ります。一方、GoUsageLimitErrorはresponse headerのretry-afterを読み、countdownを組み立てます。これはsource-code snapshotの確認であり、あなたのinstalled versionやaccountを実行して測定した結果ではありません。

公開feature request #53252 と #52894 には正確なreset時刻の例が書かれていますが、それらは要望を説明するsampleであり、観測された無料枠のscheduleではありません。Issueがclosedになっていても、使用中のclient versionへ実装済みとは限りません。

2026-10-10に開いたOpenCode Goの公式documentでは、有料usageについて5-hour、weekly、monthlyのwindowを別に定義しています。Goのwindowから無料modelのreset周期を推定することはできません。

判断ルールは次のとおりです。

• countdownまたは正確な時刻が表示される: 文言、time zone、providerを保存し、その時刻付近で1回だけ再試行する。
• 時刻が表示されない: reset時刻はunknownとして扱い、短時間の連続retryや別planのwindowによる代用をしない。
• 一般的な429だけが表示される: 無料枠と判明するまでprovider throttlingやoverloadを調べる。

選択肢1：同じ無料modelが必要なら待つ

Taskが緊急ではなく、別APIのusageを発生させたくなく、errorが明確に無料枠を示している場合は、待つのが最も単純です。

1. 最後に失敗した時刻とraw errorを記録する。
2. Quota問題と一時的なrate limitを混同しないよう、連続retryを止める。
3. 信頼できるtimerがあれば、その時刻付近で試す。Timerがなければ、許容できる間隔で確認し、固定周期を約束しない。
4. 多数のfileを読む・変更するtaskではなく、短いrequestで先に検証する。

成功とは、OpenCodeが起動したことやprocessのexit codeが0だったことではありません。選択したmodelが新しい実responseを返し、元のerrorがすぐ再発しないことが必要です。

選択肢2：/modelsに現在出ている別modelへ切り替える

作業を続けたいが元のmodelである必要がない場合は、accountに現在表示され、想定したproviderから利用できる別entryを選びます。

切り替える前に、次を確認します。

• Modelが古いtutorialだけでなく、現在のlistに存在する。
• Entryが想定したproviderに属し、model変更が知らないうちにaccountやbillingの変更になっていない。
• Modelがtaskに適している。Repositoryの変更を許可する前に、短いcode理解またはtool use requestで確認する。

Modelの切り替えは保証ではありません。別の無料modelにも独自limit、地域制限、一時停止、容量問題があり得ます。正しい案内は「現在利用可能なmodelを選んで検証する」であり、「無料modelを変えれば必ず復旧する」ではありません。

選択肢3：独立課金のproviderを明示的に使う

Deadlineがあり、別APIのusageを許容でき、今後のrequestをZen無料枠から分離したい場合に使います。これは無料quotaのresetではありません。以後のcallが別account、別API Key、別usage recordを通るようになります。

OpenCode provider documentではcustom OpenAI-compatible providerに対応しています。最小手順は次のとおりです。

1. /connectを実行し、Otherを選び、一意のprovider IDを入力してcredential fieldにAPI Keyを保存する。
2. opencode.jsonで同じprovider ID、正しいBase URL、実際のModel IDを設定し、fileを保存する。
3. 新しい設定を確認する前にOpenCodeを完全終了し、同じprojectで再起動する。すでに開いているTUIが新しいproviderをhot reloadすると仮定しない。以前のtask contextが必要なら、project directoryと戻るべきtaskまたはsessionを控え、再起動後に環境で利用できる方法を使って安全に戻る。
4. 再起動後に/modelsを実行し、新しいentryが表示されることを確認してから、表示名だけでなく正確なproviderId/modelIdを選ぶ。
5. Fileを変更しないよう明示した小さなrequestを送り、実際の新しいmodel responseを確認する。
6. 対象providerのrequest log、usage record、balance changeを確認し、そのrequestが実際に処理されたことを検証する。対応する記録がなければ、切り替えを検証済みとしない。

BetterTokenは、この独立routeで選べるproviderの一つです。2026-10-10に開いたBetterTokenのOpenCode設定documentでは、Base URLをhttps://www.bettertoken.ai/v1、model参照をbettertoken/YOUR_MODEL_IDのように指定します。Base URLへ/chat/completionsを追加せず、top-levelのmodelをmodels内の実際のIDと完全に一致させます。

境界は明確です。BetterTokenはZen無料枠を提供せず、OpenCode/Zenのlimitをresetしません。すべての429を避けられる保証も、同条件のusage比較なしに必ず安いという保証もありません。独立したAPI routeであり、無料枠の修復ではありません。

小さなrequestで本当に復旧したか確認する

待機、model変更、provider変更のどれでも、同じacceptance testを行います。

1. Interfaceでもう一度、選択中のprovider/modelを確認する。
2. Fileを変更せず、単語READYだけを返すよう求めるrequestを送る。
3. Responseと時刻を保存し、config受付の通知やcache済みoutputではなく、新しいmodel responseであることを確認する。
4. 独立providerでは、usage record、request log、balanceに対応する小さな変化があるか確認する。Providerがその情報を出さない場合、billingまで確認済みとは書かない。
5. 元のerrorが再発しなければ本来のtaskへ戻り、最小の意味あるstepから実行する。

有効なPASSには、実response、期待したprovider/model、provider側のusage evidenceがそろう必要があります。Configがparseできた、clientが起動した、exit codeが正常だった、という事実だけでは不十分です。

小さなrequestも失敗する場合

すべての修正を繰り返すのではなく、新しく出たerrorのbranchへ進みます。

• 同じFree limit reached: quotaがまだ戻っていないか、選択が実際には変わっていません。/modelsとproject configを再確認します。
• 401: そのproviderのcredentialを確認します。opencode auth listを実行し、必要なら/connectをやり直します。
• 404またはModel not available: Base URL、Model ID、providerId/modelIdを確認し、opencode modelsで現在のaccessを調べます。
• 一般的な429またはoverload: provider throttlingとして扱い、retry頻度を下げてstatusを確認します。Zen無料枠の問題として扱い続けないでください。
• Error情報が不足: OpenCode troubleshooting guideでlogを確認し、時刻、provider、model、status、secretを除いたresponse bodyを付けて報告します。

API Keyをissue、screenshot、chatへ貼り付けないでください。必要なerror情報は残し、Authorization headers、token、その他credentialを削除します。

よくある質問

OpenCodeの無料枠は毎日決まった時刻にresetしますか？

すべての無料modelが同じdaily、weekly、monthly cycleを共有するという信頼できる一次情報はありません。現在のrequestに時刻が出る場合だけ使い、出ない場合はunknownとします。

429は必ず無料枠の消費を意味しますか？

いいえ。通常のprovider rate limit、concurrency limit、overloadでも発生します。provider、model、response body、error typeを組み合わせて判断します。

OpenCode Goへ加入する以外に続ける方法はありませんか？

あります。待つ、現在利用可能な別modelを選ぶ、独立providerを明示的に使う、という方法があります。Goは別の有料planであり、そのwindowは無料modelのreset根拠ではありません。

BetterTokenへ切り替えると無料limitが消えますか？

いいえ。独自のAPI Key、Base URL、Model ID、usage accountingを持つ独立provider routeです。Zen無料枠の状態は変わりません。

実践上の結論

Free limit reachedをreset周期の推測で解決しないでください。実際のprovider/modelを特定し、表示されたresetだけを信頼し、deadlineに応じて待機、/modelsの現在利用可能なmodel、独立課金providerを選びます。本来のtaskへ戻る前に、小さなresponseとprovider側usageで復旧を証明します。