ドキュメント · ヘルプ

よくあるエラーの直し方：401・429・502・504 など

magpie のゲートウェイのエラーは、何が起きたかを自分の言葉で伝えます。このページでは、よくあるエラーとその原因、直し方をまとめます。

すべてのリクエストは magpie の ルーティング ページに並び、どのプロバイダとアカウントに送られ、各試行がどう終わったかが分かります。リクエストの レポートをコピー で、質問に必要な情報をコピーできます。

401 と 403：キーやサインインが拒否された

ベンダーから。プロバイダが magpie の送ったキーやサインインを拒否しました。magpie はそのキーやアカウントを休ませて次を試すので、エラーが見えるのは残りがないときだけです。サインインの期限切れはそう書かれます（例：“the ChatGPT sign-in has expired — sign in again”）。

• 直し方：＋ プロバイダを追加（または magpie accounts add <provider>）からサインインし直すか、プロバイダに新しいキーを設定します。

magpie 自身から。次の場合、magpie は何も送らずに 403 を返します。

429 と休止

429 はクォータ切れ、残高不足、レート制限のいずれかです。magpie は拒否されたキーやアカウントを休ませ、リクエストを次のアカウント、ルーティンググループの次のメンバー、またはプロバイダの フォールバック に送ります。プロバイダの行には 休止中 · {why} · {time} に復帰 と表示されます。

• 今すぐもう一度。今すぐ試す は休止を終えます。次のリクエストで再び使われ、再度拒否されれば通常どおり休止します。
• 休止の上限。magpie provider rest-cap <id> 4h でプロバイダの最長休止を設定します。off にすると、理由の分からない失敗では休止しません。
• 上限がすぐ戻る中継サービス。プロバイダ編集の 詳細設定 で クォータ切れやレート制限で一時的に外す のチェックを外すと、429 で休止せず、次のリクエストもいつもどおり送られます。
• 1 つに頼らない。アカウントやフォールバックのモデルをもう 1 つ追加すれば、1 つが切れてもエージェントは止まりません。magpie accounts で各アカウントの使用量が分かります。

休止は再起動後も保たれるので、magpie を終了しても休止中のアカウントは早く戻りません。

502：プロバイダが応答しない

502 は、magpie がプロバイダから API の返答を得られなかったことを示します。プロバイダ名に続く文で、どの場合かが分かります。

• “didn’t answer: …”接続に失敗しました：名前が解決できない、接続が拒否された、プロキシが止まっている、など。コンピュータがまったくネットワークにつながっていないときは、magpie がそれに気づき、どのプロバイダも休ませません。
• “… not an API reply”プロバイダは応答しましたが、Web ページ（サインインページ、Cloudflare のチャレンジ）、空の本文、JSON でない内容でした。たいていはベース URL が API ではなく Web サイトを指しています。ベンダーのドキュメントと照らし合わせ、/v1 で終わるべきかも確認してください。
• OpenCode：“… which is no error, not an API reply”。OpenCode のゲートウェイは、モデル名だけを含む 400 を返すことがあります。同じリクエストは数秒後に通るので、magpie はこれを 502 とみなし、リクエストの待ち時間内に再試行するか、グループの次のメンバーを試します。誰も休ませません。非常に大きなツール一覧を含むリクエストで起きます。

502、503、504、529、Cloudflare の 520〜524 は「混雑」として扱われ、エージェントに返す前に再試行するか、ルーティンググループの次のメンバーに移ります。

504：時間内に応答がない

• “<provider>: no first token in Ns”。ルーティンググループは各メンバーに応答開始までの時間（最初のトークン）を与えます。それを過ぎたので次のメンバーに移りました。遅いモデルにはグループで長くします。
• “no member of the group answered within its Ns budget”。グループの時間内に全メンバーを試し、どれも応答しませんでした。
• “magpie held this request for … without routing it to any provider”。リクエストが magpie の中で待ちすぎたため、待たせ続けずに止めました。送り直してください。繰り返すときは、ルーティング ページでそのリクエストの レポートをコピー して共有してください。

モデルが見つからない（404）

エラーは magpie knows no model “…” で、did you mean …? とプロバイダ id の一覧が付くことがあります。

• magpie の名前で指定する。magpie models が表示する provider/model、ルーティンググループの id か名前、またはプレフィックスなしのモデル id を使います。
• “… is switched off in Magpie, so … is not served”。プロバイダかルーティンググループがオフです。プロバイダページかルーティングページでオンに戻します。
• プロバイダがまだない。エラーに “add a provider in magpie first” と出ます。

エージェントにモデルが出ない

• エージェントを再起動する。多くのエージェントは起動時にだけ設定を読みます。変更後、magpie はエージェントの行でそう知らせます（例：Codex は起動時にモデル一覧を作る）。Codex アプリは app-server も動かし続けるので、案内どおりに再起動してください。
• magpie が提供しているか確認する。magpie models に選べるモデルがすべて並びます。オフにしたモデルや、プロバイダがオフのモデルは出ません。
• Claude Code。/model に “via magpie” 付きでモデルが並びます。シェルで CLAUDE_CODE_USE_BEDROCK や CLAUDE_CODE_USE_VERTEX が設定されていると、Claude Code は magpie ではなくそのクラウドに接続します。シェルのプロファイルから外してください。

ポート 3425 が使用中

ゲートウェイは 127.0.0.1:3425 で待ち受けます。変えるには 設定 › ネットワークと共有 › ゲートウェイのアドレス を開きます。設定できるのはポート（1024〜65535）だけで、magpie が接続したエージェントも一緒に移ります。

WSL のエージェント

Windows では、magpie は実行中の WSL ディストリビューションから Claude Code、Codex、OpenCode、Kimi Code、Qwen Code などのエージェントを探します。見つかったものはそれぞれエージェントページに自分の行を持ち、Windows と同じように設定されます。停止中のディストリビューションを起動することはありません。

• エージェントが出ない。ディストリビューションを起動し、設定 › 一般 › WSL のエージェントを検出 がオンか確認します。
• magpie に届かない。WSL 既定の NAT ネットワークでは、magpie は WSL ネットワーク上の Windows のアドレスでも専用のキーでゲートウェイを提供し、そのアドレスをエージェントの設定に書き込みます。ミラーモードでは、エージェントは Windows と同じく 127.0.0.1 を使います。通すかどうかは Windows ファイアウォールが決め、WSL のネットワークは「パブリック」扱いです。接続が遮断されるときはそこで magpie を許可してください。
• 変更が反映されない。WSL のエージェントは起動時に設定を読みます。WSL 側で再起動してください。

ネットワーク上の別のコンピュータから

既定では、ゲートウェイはこのコンピュータにだけ応答します。別のコンピュータから使うには 設定 › ネットワークと共有 › ローカルネットワークで共有 をオンにします。相手のコンピュータは ゲートウェイ ページの ゲートウェイキー のキーを送ります。

• “magpie isn’t shared on the local network”。magpie を動かしているコンピュータで共有をオンにします。
• 401。キーがない、オフ、または期限切れです。有効なゲートウェイキーを Authorization: Bearer <key> か x-api-key で送ります。
• 特定のモデルで 403。キーが一部のモデルに限られています：magpie gateway-key models <id>。

ポートをインターネットに公開しないでください。コンピュータ間は VPN を使います。別の magpie への接続を含む設定の全体は リモート magpie にあります。

プラグインに移ったサブスクが使えない

Command Code、Cursor、Devin、Factory、Grok、Kiro、Xiaomi MiMo、Qoder、WorkBuddy、ZCode、Zed は magpie に組み込まれなくなり、それぞれ同じ働きをするコミュニティプラグインが提供します。以前に追加したアカウントはプラグインへの移行が必要で、移行するまで使えません。

• 直し方：プロバイダ一覧の上に「… の組み込みサブスクリプションは終了しました。アカウントはまだプラグインに移行されていません」と出ます。プラグインに移行 を押すと、magpie がプラグインをインストールし、各アカウントを確認します。移行してもアカウント、モデル、エージェントはそのままです。magpie は自動でも移行し、プラグイン ページからプラグインをインストールしても移行されます。

移行後のエラーはプラグインから来ています。サインイン、モデル、リクエストはプラグインが処理します。

よくある質問

プロバイダは動いているのに、なぜ 502 になるのですか？

プロバイダが Web ページや空の本文など、API の返答でないものを返しました。たいていはベース URL が API ではなくベンダーの Web サイトを指しています。

429 のあと、なぜアカウントが使われないままなのですか？

magpie はベンダーが示したリセットまで、示されなければしばらくの間そのアカウントを休ませます。プロバイダの行に復帰時刻が出ており、「今すぐ試す」で休止を終えられます。

“magpie knows no model” とはどういう意味ですか？

その名前のモデルを提供するプロバイダがありません。magpie models が表示する provider/model で指定するか、プロバイダをオンに戻します。

magpie のポートを変えるには？

設定 › ネットワークと共有 › ゲートウェイのアドレス です。magpie が接続したエージェントも一緒に移ります。

WSL のエージェントから Windows の magpie を使えますか？

使えます。magpie は実行中の WSL ディストリビューションのエージェントを見つけ、届くアドレスで設定します。NAT ネットワークでは、Windows ファイアウォールが WSL からの接続を通す必要があります。

別のコンピュータから magpie を使えますか？

使えます。設定 › ネットワークと共有 › ローカルネットワークで共有 をオンにし、相手のコンピュータからゲートウェイキーを送ります。ポートはインターネットに公開しないでください。

解決しないときは、ルーティングページでそのリクエストのレポートをコピーして Discord で質問してください。