Claude Code 403, 503, and 529 Errors: Find the Source, Then Fix

A status code in Claude Code tells you what went wrong, not who said it. The same 403 can come from your corporate proxy, from Anthropic refusing your account or region, from a firewall in front of your company's LLM gateway, or from a website that won't let Claude fetch a page. A 503 almost never comes from Anthropic's API at all, and a 529 almost always does.

So the first move is the same for all three: run /status inside Claude Code and look for an Anthropic base URL line. If it's there, every request goes through that gateway or relay first, and that's the first place to look for a 403 or 503. If it's missing, you're talking to Anthropic directly (or to Amazon Bedrock, Google Cloud, or Microsoft Foundry if you configured one), and the fix is on your network or your account.

The quick map, as of September 29, 2026:

• 529 Overloaded: Anthropic (or the cloud provider named in the message) is out of capacity for that model. It isn't your quota. Switch models with /model.
• 503 with text like No available accounts, No available channel, No available provider, or no available server: the gateway, relay, or load balancer you're pointed at has nothing healthy to send your request to. Only its operator can fix that.
• 403: find the variant below. Request not allowed after login is usually subscription, role, or proxy; an HTML 403 Forbidden behind a gateway is usually a firewall rule; App unavailable in region means Claude Code isn't offered where you are.

Find out who answered the request

Claude Code shows you three clues, and together they almost always settle the question.

The /status screen. It opens on the Status tab. According to Anthropic's gateway setup guide, the Anthropic base URL line only appears when a gateway address is set. Next to it, an Auth token or API key line names the credential variable in use, while a Login method line naming a claude.ai account means you're signed in with your subscription. If you set the base URL both in your shell and in a settings file's env block, the settings file wins, so /status is more reliable than echo.

The end of the error message. For any 5xx, Claude Code prints the status code, the upstream's message, and a closing sentence that names where to check health. The error reference says that sentence points to status.claude.com on the Anthropic API, to the provider's own status page on Bedrock, Google Cloud's Agent Platform, or Foundry, and to the gateway host when ANTHROPIC_BASE_URL is set. A real relay error from August 2026 ended with check your inference gateway (...) followed by the relay's domain.

Whether the message looks like an HTML page title. When a proxy, load balancer, or gateway answers with an HTML error page, Claude Code v2.1.281 and later show the status code plus the page title, such as API Error: 502 Bad Gateway or API Error: 403 Forbidden. A short, generic title like that is a sign that a web server or firewall answered, not the model API.

One caveat changes how much you can trust the tail. Older builds didn't name the gateway: users on Claude Code 2.1.137 reported relay errors that still ended with "check status.claude.com" (issue #57554). Check claude --version. On older builds, go by /status, not by the last sentence.

Match your exact message

Find the row closest to what you see, then jump to that section. "Base URL line" means the Anthropic base URL line in /status.

403: proxy, account, region, or gateway

Anthropic's documented meaning of 403 on the Claude API is permission_error: the credential doesn't have permission for that resource. Claude Code's own troubleshooting pages add two network causes, "a proxy or network filter blocking the host" and "Claude Code is not available in your region." Everything below is one of those, or a middle layer that borrows the same code.

"Request not allowed" right after you log in

This is the most common direct-to-Anthropic 403. The installation and login troubleshooting page lists three checks:

1. Pro or Max subscription: confirm it's active at claude.ai/settings.
2. Claude Console (API) account: your account needs the "Claude Code" or "Developer" role. An admin assigns it in the Console under Settings → Members.
3. Behind a proxy: corporate proxies can interfere with API requests even when the browser works fine.

If /status shows an API key line when you meant to use your subscription, an old ANTHROPIC_API_KEY in your shell profile is being used instead of your login. Remove it and start a new terminal.

A related message appears on the sign-in page instead of in the terminal: Claude Code access has not been granted for this account. Contact your administrator. Your Claude Enterprise organization put you on a Custom role, and none of your custom roles grants Claude Code. Nothing you change locally fixes it. An Owner has to assign a role that includes Claude Code, then you run claude and log in again.

403 only in VS Code or another IDE

If the terminal works and the extension doesn't, the extension probably isn't seeing the same environment. Anthropic's VS Code guide notes that VS Code may not inherit your shell environment. The note is about ANTHROPIC_API_KEY, but proxy variables travel the same way. Three ways to fix it:

• Quit VS Code and launch it from a terminal with code ., so it inherits your exported variables.
• Set the variables in the extension's environmentVariables setting, which applies to the Claude process only.
• Put them in the env block of ~/.claude/settings.json, which the CLI and the extension share. This is the most durable option.

For other VS Code symptoms that aren't a 403, see Claude Code Not Working in VS Code? Check the Failing Surface First.

Proxy variables that don't reach Claude Code

Claude Code reads https_proxy, HTTPS_PROXY, http_proxy, and HTTP_PROXY, and uses the first one set in that order, plus NO_PROXY for exceptions. A proxy that needs a login goes in the URL itself, as in http://username:password@proxy.example.com:8080. Two details trip people up:

• Claude Code takes its proxy from these environment variables. A proxy configured only in your browser or in OS network settings may not apply to it.
• Claude Code does not support SOCKS proxies, per its network configuration page. A socks5:// value won't work; use the proxy's HTTP or HTTPS port.

If the proxy refuses the connection outright, you'll usually see a connection error rather than a 403; that path is covered in Claude Code Unable to Connect to API: Fix ECONNREFUSED, ECONNRESET, and Proxy Errors.

"App unavailable in region"

If the install page or a connectivity check returns App unavailable in region, Claude Code isn't offered in the country you're connecting from. Anthropic's supported countries list includes the United States, Japan, South Korea, Spain, and Taiwan. As of September 29, 2026, China, Russia, Hong Kong, and Macau are not on it. No setting on your machine changes that outcome. Trying to route around the restriction puts the account at risk, so in an unsupported region the right move is to stop, not to retry.

A bare 403 during installation (curl: (22) The requested URL returned error: 403) often has the same cause. If you're in a supported country, it usually means a corporate proxy or firewall is blocking downloads.claude.ai instead.

HTML "403 Forbidden" through a gateway

This one is easy to misread. You have a base URL line, the gateway's one-token test (below) passes, yet real sessions fail with API Error: 403 Forbidden, and the gateway's own logs show no request at all.

According to the gateway troubleshooting table, a web application firewall or reverse proxy in front of the gateway blocked the request body before the gateway saw it. Claude Code prompts contain XML-style tags and source code, which match cross-site-scripting body rules. A short test prompt doesn't. The fix is on the gateway side: exempt the /v1/messages path from request-body inspection. On AWS WAF that's the CrossSiteScripting_Body managed rule; on nginx with ModSecurity, the equivalent OWASP CRS body rules.

Gateways and endpoints that refuse on their own terms

• Gateway refused the request · signing in again won't change this — check with your gateway administrator · API Error: 403 ... appears when you're signed in through a Claude apps gateway and the gateway or its upstream refused. Logging in again won't help. The part after API Error: is the refusal your administrator needs. Builds before v2.1.273 showed a generic Please run /login here instead.
• This service is restricted to the official Claude Code client has been reported only against third-party endpoints, and Anthropic doesn't document it. It's that endpoint's own client check. Take it to whoever runs the endpoint.

403 when Claude fetches a web page

If Claude tells you it got a 403 while fetching a URL, your API access is fine. The target website, or a CDN such as Cloudflare in front of it, refused an automated request. Paste the content you need into the chat, or, if you own the site, adjust its bot or firewall rules for that path.

Don't delete ~/.claude for a 403

Some guides tell you to rm -rf ~/.claude and log in again. That folder holds your settings, history, and credentials, and wiping it changes nothing about your region, proxy, role, or gateway. If you suspect a stale login, run /logout, then /login.

503: usually the gateway, relay, or load balancer

The documented Claude API error list, as of September 29, 2026, runs 400, 401, 402, 403, 404, 409, 413, 429, 500, 504, and 529. There is no 503. When the Messages API is out of capacity, it answers with 529. So if you see a 503 and /status shows a base URL line, start from the assumption that the middle layer produced it.

The wording tells you which kind of middle layer:

• No available accounts: an account-pool relay that spreads your requests across a pool of upstream accounts. In sub2api, an open-source relay of this kind, the message comes back as a 503 when every account that could serve your model is temporarily exhausted (rate-limited, auto-paused on quota, blocked) or when your group has no accounts at all. If the group has accounts but none is set up for the model you asked for, sub2api returns a 404 model_not_found instead. If every account is rate-limited, it sends a 429 reading "All available accounts are currently rate-limited." Other relay software may use the same phrase, so treat sub2api as an example, not a diagnosis.
• No available channel for model X under group Y: new-api and its forks. The relay has no working channel for that exact model in your user group. In a public August 2026 report, a user who had just topped up a relay balance got it when requesting the newest Opus model. The new-api project's own issue template says problems on hosted third-party instances belong to their operator.
• No available provider found: Claude Code Hub. Its troubleshooting page lists four causes: all providers disabled, all circuit breakers open, group restrictions that match nothing, or a concurrency limit reached. The fix is in its admin panel.
• no available server: the exact text Traefik returns, with a 503, when its load balancer has no healthy backend (source). Anthropic doesn't document running Traefik. If you see this string, the most likely explanation is that the relay or self-hosted gateway behind your base URL is down or restarting.
• no healthy upstream: standard Envoy wording, and Claude Code users have posted it during service problems. Without a base URL line and with an incident on status.claude.com, it's Anthropic's edge, so wait. With a base URL line, check the gateway first, because the proxy that answered may be the gateway's own.

What to do with a middle-layer 503:

1. Run the one-token test in the next section. If it fails the same way, the problem is upstream of you, and changing your Claude Code config won't help.
2. Try another model with /model. Pools and channels are often configured per model, so a different one may be served.
3. Send the operator the evidence listed at the end of this guide. Topping up your balance doesn't add accounts or channels to the relay.
4. If you own the gateway, check its admin view for disabled providers, open circuit breakers, or backends failing health checks.

A 503 without a base URL line is rarer. Check the provider status page named in the message and wait a few minutes. If it persists with no incident posted, report it with /feedback.

529: Anthropic's capacity, not your quota

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. means the model you're using is at capacity across all users. Claude Code has already retried up to 10 times with exponential backoff before printing it, and the error reference is explicit that a 529 is not your usage limit and doesn't count against your quota.

Capacity is tracked per model, so the fastest fix is /model and a different model. Claude Code sometimes suggests this itself, with a message like Opus is experiencing high load, please use /model to switch to Sonnet. Behind a gateway, the closing sentence names the gateway host instead of Anthropic's status page. Check there first.

Fallback chains and settings for CI jobs that should wait instead of failing are covered in Claude Code API Overloaded (529): Switch Models or Add a Fallback. If a long task died mid-run, Claude Code 500 vs 529: Resume Safely Without Duplicating Work explains how to pick it back up.

Verify each layer from your terminal

Run these from the same shell you launch Claude Code from. Each one rules a layer in or out.

1. Are you on a gateway at all? Inside Claude Code:

/status

Base URL line present: go to step 4. Missing: steps 2 and 3.

2. Can this shell reach Anthropic directly?

curl -sI https://downloads.claude.ai/claude-code-releases/latest
curl -I https://api.anthropic.com

On Windows PowerShell, use curl.exe instead of curl. A 200 on the first command means you reached the download server. A 403 there points to a proxy or network filter, or to an unsupported region. No output or a timeout means your network is blocking the connection.

3. Is a proxy or leftover base URL set where you don't expect it?

env | grep -i -E '_proxy|ANTHROPIC_BASE_URL'
grep -n -A8 '"env"' ~/.claude/settings.json

If curl works but Claude Code doesn't, a leftover ANTHROPIC_BASE_URL is a common cause. Claude Code sends model requests to that address instead of api.anthropic.com. Also check the env block of project settings files in .claude/.

4. Does the gateway itself answer? This one-token request comes from Anthropic's gateway guide:

curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

If your gateway expects the key in x-api-key, swap the Authorization header for x-api-key: $ANTHROPIC_API_KEY. How to read the result:

• A JSON body starting with {"id":"msg_: the gateway is reachable and your credential works.
• An error about an unknown model: URL and credential still work. The gateway authenticated you before rejecting the model name.
• 401: the credential was rejected.
• The same 503 text you saw in Claude Code: the gateway or relay has the problem, not your setup.
• A pass here but 403 Forbidden in real sessions: the firewall body-inspection case above.

For how the base URL and token should be set in the first place, see Claude Code API Configuration: Keys, Settings, Models, and Gateways.

What to send when you escalate

Whoever answered the request needs enough to find it in their logs. Collect this before you write:

• The full error line, copied as text, including any request ID. Some relays put one in parentheses.
• The Anthropic base URL and credential lines from /status, with the token itself removed.
• Your claude --version, the model you had selected, and the time it happened, with your time zone.
• The result of the one-token curl test, or of curl -I https://api.anthropic.com if you're not on a gateway.

Where to send it depends on who answered. Relay 503s and gateway 403s go to the relay operator or your gateway administrator. For "Request not allowed" or role problems, contact your organization's Console admin or Enterprise Owner. For a persistent Anthropic-side 5xx with no posted incident, run /feedback inside Claude Code. On Bedrock, Google Cloud, Foundry, and other third-party providers, /feedback saves a local archive you can pass to your Anthropic account representative instead.

FAQ

Does a 403 in Claude Code mean my account is banned?

Usually not. The documented causes are an inactive subscription, a missing Console role, a proxy or network filter, an unsupported region, or a gateway or firewall refusing the request. Check /status and the exact message first. A 403 on its own doesn't tell you an account was suspended.

Is Anthropic down when Claude Code shows a 503?

Only if /status shows no base URL line and an incident is posted on status.claude.com. The documented Claude API errors don't include 503, and messages like No available accounts or No available channel come from relay software, not from Anthropic.

Should I keep retrying a 529?

Not by resending the same message right away. Claude Code has already retried up to 10 times before showing it. Switch models with /model, or try again in a few minutes. The 529 doesn't use up any of your quota.

Why does the terminal work but the VS Code extension returns 403?

VS Code often doesn't inherit variables you exported in your shell, including proxy settings and API keys. Launch it with code ., or move the variables into the env block of ~/.claude/settings.json, which both the CLI and the extension read.

Will switching to a different gateway or relay fix these errors?

Only if the current one is what's failing. A relay can fix a relay-side 503. It can't fix a region restriction, an inactive subscription, or a firewall on your own network, and every relay adds a layer that can produce its own 403s and 503s. The diagnosis above works the same no matter whose base URL is in /status.