Docs · Help

Fixing common errors: 401, 429, 502, 504 and more

An error from magpie’s gateway says what went wrong in its own words. This page lists the common ones, what causes them, and the fix.

Every request is listed on magpie’s Routing page, with which provider and account it went to and how each try ended. Copy Report on a request copies what you need to ask for help.

401 and 403: a key or sign-in refused

From the vendor. The provider turned down the key or sign-in magpie sent. magpie sets that key or account aside and tries the next one, so you see the error only when none is left. A sign-in that has run out says so, for example “the ChatGPT sign-in has expired — sign in again”.

• Fix: sign in again from ＋ Add provider (or magpie accounts add <provider>), or give the provider a new key.

From magpie itself. magpie answers 403 on its own in a few cases, before anything is sent:

429 and rest periods

A 429 means the provider is out of quota, out of credit or rate limiting you. magpie rests the key or account that was refused and sends the request to the next account, the next member of a routing group, or the provider’s Fallback. The provider’s row shows Resting · {why} · back at {time}.

• Ask it again now. Try now ends the rest: the next request asks it again. Refused again, it rests again.
• Cap the rest. magpie provider rest-cap <id> 4h sets the longest rest for a provider; off stops it resting for failures that say nothing of why.
• A relay whose limits pass in a moment. Untick Set it aside when out of quota or rate limited in the provider editor’s Advanced: a 429 then rests nothing, and the next request goes to it as usual.
• Never all at once. Add a second account or a fallback model, so a spent one never stops the agent. magpie accounts shows how much of each account’s allowance is used.

Rests are kept across restarts, so quitting magpie doesn’t bring a resting account back early.

502: the provider didn’t answer

A 502 means magpie couldn’t get an API reply from the provider. What follows the provider’s name says which case it is:

• “didn’t answer: …” The connection failed: a name that doesn’t resolve, a refused connection, a proxy that is down. When this computer has no network at all, magpie notices and rests nobody.
• “… not an API reply” The provider answered, but with a web page (a sign-in page, a Cloudflare challenge), nothing at all, or something that isn’t JSON. The base URL usually points at a web site instead of the API: check it against the vendor’s docs, and whether it should end in /v1.
• OpenCode: “… which is no error, not an API reply”. OpenCode’s gateway sometimes answers a 400 holding only the model’s name. The same request is answered some seconds later, so magpie reads it as a 502, asks again within the request’s patience or tries a group’s next member, and rests nobody. It is tied to requests carrying very large tool lists.

A 502, 503, 504, 529 or Cloudflare’s 520 to 524 counts as busy: magpie asks again or moves to a routing group’s next member before the agent sees it.

504: no answer in time

• “<provider>: no first token in Ns”. A routing group gives each member a time to start answering (First token). The member was slower, so the next was asked. Raise it on the group for a slow model.
• “no member of the group answered within its Ns budget”. Every member of the group was tried within the group’s time and none answered.
• “magpie held this request for … without routing it to any provider”. The request waited inside magpie and was stopped rather than left waiting. Send it again; if it comes back, Copy Report on that request on the Routing page and share it.

Model not found (404)

The error reads magpie knows no model “…”, often with did you mean …? and the list of your provider ids.

• Name it as magpie does. Use provider/model, as magpie models lists it, a routing group’s id or name, or a bare model id.
• “… is switched off in Magpie, so … is not served”. The provider or routing group is off. Switch it on again on the Providers or Routing page.
• No providers yet. The error says “add a provider in magpie first”.

The agent doesn’t show the model

• Restart the agent. Most agents read their config only when they start. magpie says so on the agent’s row after a change, for example “Codex builds its model list at start-up”. Codex’s app also keeps an app-server running; restart it as the notice says.
• Check magpie serves it. magpie models lists every model you can pick. A model you turned off, or one whose provider is switched off, isn’t listed.
• Claude Code. /model lists magpie’s models marked “via magpie”. If CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX is set in your shell, Claude Code goes to that cloud instead of magpie; remove it from your shell profile.

Port 3425 is in use

The gateway listens on 127.0.0.1:3425. To move it, open Settings › Network and sharing › Gateway address. Only the port is set there, 1024 to 65535, and the agents magpie connected move with it.

Agents in WSL

On Windows, magpie looks in running WSL distros for agents such as Claude Code, Codex, OpenCode, Kimi Code and Qwen Code. Each one it finds gets a row of its own on the Agents page, and magpie sets it up as it does on Windows. It never starts a stopped distro.

• The agent isn’t listed. Start the distro, and check Settings › General › Detect agents in WSL is on.
• It can’t reach magpie. Under WSL’s default NAT networking, magpie also serves the gateway at Windows’ address on the WSL network, with a key of its own, and writes that address into the agent’s config. With mirrored networking the agent uses 127.0.0.1 as on Windows. Windows’ firewall still decides: WSL’s network counts as Public, so allow magpie there if the connection is blocked.
• A change doesn’t show. An agent in WSL reads its config at start-up: restart it there.

From another computer on the network

By default the gateway answers only this computer. To use it from another: Settings › Network and sharing › Share on local network. The other computer sends a gateway key from the Gateway page’s Gateway keys.

• “magpie isn’t shared on the local network”. Turn sharing on, on the computer that runs magpie.
• 401. The key is missing, off or expired. Send an enabled gateway key as Authorization: Bearer <key> or x-api-key.
• 403 for a model. The key is held to some models: magpie gateway-key models <id>.

Don’t open the port to the internet; use a VPN between your computers. The full setup, another magpie included, is in Remote magpie.

A subscription moved to a plugin isn’t served

Command Code, Cursor, Devin, Factory, Grok, Kiro, Xiaomi MiMo, Qoder, WorkBuddy, ZCode and Zed are no longer built into magpie. Each is served by a community plugin that does the same job. Accounts added before still need to move to the plugin, and nothing serves them until they do.

• Fix: a line over the Providers list says “… built-in subscription is retired, and its accounts haven’t moved to its plugin yet”. Press Move to the plugin: magpie installs the plugin and checks each account. Moving keeps your accounts, models and agents as they are. magpie also moves them by itself, and installing the plugin from the Plugins page does too.

An error after the move comes from the plugin, which does the sign-in, models and requests.

FAQ

Why does magpie answer 502 when the provider is up?

The provider answered with something that isn’t an API reply, such as a web page or an empty body. The base URL usually points at the vendor’s web site instead of its API.

Why does an account stay unused after a 429?

magpie rests it until the reset the vendor named, or for a while if none was named. The provider’s row says when it is back, and Try now ends the rest.

What does “magpie knows no model” mean?

No provider serves a model by that name. Name it as provider/model, as magpie models lists it, or switch its provider on again.

How do I change magpie’s port?

Settings › Network and sharing › Gateway address. The agents magpie connected move with it.

Can an agent in WSL use magpie on Windows?

Yes. magpie finds agents in running WSL distros and sets each up with an address it can reach. Under NAT networking, Windows’ firewall must let WSL’s connection through.

Can I use magpie from another computer?

Yes. Turn on Settings › Network and sharing › Share on local network, and send a gateway key from the other computer. Don’t open the port to the internet.

Still stuck? Copy the request’s report from the Routing page and ask on Discord.