Troubleshooting

A request travels through three hops, and each hop has its own kind of error:

AI CLI  →  sotatek-proxy (127.0.0.1:3817)  →  Bifrost gateway  →  Provider (Anthropic/OpenAI/…)

Source	How to recognise it
sotatek-proxy	Body {"error":"upstream unreachable","proxy":"sotatek-proxy"} (HTTP 502), or an X-Git-Remote-Warning response header
Gateway	Body {"error":{"message":...}}. Governance errors also carry a "type" (e.g. virtual_key_blocked); the 403s in 3.1–3.4 have only a message
Provider	The provider’s own message/type, usually with the provider’s HTTP status

When reporting an error to Admin/IT

Send the time it happened and the last 8 characters of your key. Never send the whole key.

1. Errors from sotatek-proxy

Connection refused

The proxy is not running. Check with sotatek-proxy status, start with sotatek-proxy start, and confirm your CLI points at ANTHROPIC_BASE_URL=http://127.0.0.1:3817/anthropic.

HTTP 502 upstream unreachable

The proxy cannot reach the gateway (network, VPN, DNS, or gateway down). Check your network/VPN, then look at sotatek-proxy logs. If the network is fine and it persists, contact Admin/IT.

X-Git-Remote-Warning / X-Git-Remote-Remedy headers

When the proxy cannot work out the git remote it still forwards the request and reports the cause in these two response headers. The gateway may then reject the request with the 403 in 2.1 or 2.2. Run sotatek-proxy doctor from the repo that is failing to see the cause and fix.

Cause code	Meaning	Fix
not_a_repo	The CLI was started outside any git repo (the proxy scans up to 3 parent levels)	Restart the CLI from inside the repo
no_remote	The repo has no remote	git remote add origin <url>
git_not_found	The service cannot find git	macOS: xcode-select --install (Homebrew git must be symlinked into /usr/local/bin, because launchd sees a minimal PATH). Windows: install Git for Windows, restart the service. Linux: install git, restart the service
git_shim_broken	macOS /usr/bin/git is an xcrun stub that breaks after an OS upgrade	xcode-select --install
git_ownership	git refuses a repo owned by another user	git config --global --add safe.directory <repo path>
git_permission	The proxy cannot read the repo	Check the repo’s owner/mode and the user the service runs as
git_timeout	git remote -v took over 2s (network drive, stalled credential helper)	Time git remote -v in that repo
git_exec_failed	git failed for another reason	Run git remote -v manually to see git’s own error
pid_not_found, cwd_not_found	The client exited before it could be inspected	Ignore if occasional; run sotatek-proxy doctor if persistent
inspect_timeout, inspect_failed	The process-inspection tool (lsof, /proc, Windows TCP table) failed or timed out	Run sotatek-proxy doctor and follow the OS-specific hint
non_loopback_peer	The client did not connect over loopback	Use http://127.0.0.1:3817

2. Errors from the gateway

The gateway checks, in order: key authentication → git context → git/project guard → project model guard → governance (key state, budget, rate limits).

2.1 403 — Git remote is required. Please connect through SCC proxy to register your project.

• Cause: the request has no X-Git-Remote header (called the gateway directly, or the proxy could not resolve the remote — see the section above). The gateway requires it by default unless Admin enabled bypass_git_guard on the key.
• You: go through sotatek-proxy, never directly to the gateway; run sotatek-proxy doctor in the repo.
• Contact Admin/IT if you need bypass_git_guard for CI/scripts, or the proxy runs fine and the error persists.

2.2 403 — Git remote is required. Invalid project context — please reconnect through SCC proxy.

• Cause: X-Git-Remote is present but is invalid or empty base64.
• You: restart the proxy (sotatek-proxy stop, then start) and make sure no other tool adds this header.
• A valid header whose content has no usable remote is not rejected; the request just isn’t linked to a project.

2.3 403 — this key's project does not match the calling project's git remote

• Cause: the repo’s git remote was assigned by Admin to project A, but your key belongs to project B.
• You: use the key of the project you are working on, or request the correct key.
• Contact Admin/IT if the key is right but the error persists — the repo may be assigned to the wrong project or the key tagged wrongly. The check is skipped when the repo has no project or the key has none.

2.4 403 — requested model is not permitted

• Cause: the repo’s project has a model allowlist and the requested model is not in it. The message intentionally omits the project name.
• You: switch model. Admin/IT can add the model to the project.

2.5 403 virtual_key_blocked — Virtual key is inactive

• Cause: Admin has disabled the key.
• Check first — you may be sending the wrong key. Claude Code reads its key from environment variables and ~/.claude/settings.json; VS Code and Antigravity have their own settings. A conflict between them does not by itself cause this error, but it does if the tool sends an old or disabled key. Check:
  1. ANTHROPIC_AUTH_TOKEN in the env section of ~/.claude/settings.json, and in your shell environment.
  2. The key configured in VS Code (see VS Code) and Antigravity (see Antigravity).
  3. Settle on one valid key, then restart the CLI/IDE.
• Contact Admin/IT if you are sure the key you send is the one you were issued.

2.6 403 virtual_key_blocked — Virtual key has expired / Virtual key is not yet active

The current time (UTC) is past the key’s end_date or before its start_date. Ask Admin/IT to extend or confirm the dates.

2.7 403 virtual_key_not_found — Virtual key not found

The key (sk-bf-...) does not exist: mistyped, truncated while copying, or deleted. Re-copy it carefully; if it still fails, ask Admin/IT to reissue.

2.8 401 virtual_key_required

• Message: virtual key is required. Provide a virtual key via the x-bf-vk header.
• Cause: the gateway enforces virtual keys and the request has no valid one. The key is read from x-bf-vk, Authorization: Bearer, x-api-key or x-goog-api-key, and must start with sk-bf-; a key with another prefix counts as no key.
• You: check that ANTHROPIC_AUTH_TOKEN is set and well-formed.

2.9 401 Unauthorized / invalid_admin_api_key / 403 forbidden_for_api_key_actor

Rare for normal users. Usually an admin key (bfak_*) used on a model-call route, or the gateway requiring extra credentials. Use your sk-bf-... virtual key; otherwise contact Admin/IT.

2.10 403 model_blocked / provider_blocked

Model '<model>' is not allowed for this virtual key / Provider '<p>' is not allowed for this virtual key. Unlike 2.4, this limit is per key, not per project. Switch model/provider, or ask Admin/IT to change the key’s allowlist.

2.11 429 rate_limited / token_limited / request_limited

Example: rate limit violated for <name>: [token limit exceeded (used/max, resets every <window>)]. Wait until the reset window stated in the message and reduce call frequency. Ask Admin/IT to raise the limit if needed.

2.12 402 budget_exceeded

<scope> budget exceeded: <used> >= <max> dollars (scope: key, team, customer, provider or model). You cannot fix this yourself — contact Admin/IT, or wait for the budget cycle to reset.

2.13 429 user_budget_exceeded

user budget exceeded — contact administrator. The budget is tied to the key owner. Contact Admin/IT or wait for the reset.

2.14 400 missing_required_headers

missing required headers: <list>. Only appears when Admin configured required headers. Ask Admin/IT which headers to send.

3. Errors from the provider

4xx/5xx from the provider (bad provider key, upstream rate limit, 5xx, 529 overloaded) are relayed by the gateway with the provider’s original message, usually with the same HTTP status. For 429/5xx/529, retry after a while; if it persists, report it to Admin/IT with the time.

Quick diagnosis

1. Read the HTTP status and body to tell proxy, gateway and provider errors apart.
2. For git-related 403s (2.1–2.3), run sotatek-proxy doctor inside the failing repo.
3. For key errors (2.5–2.8), check which key is actually being sent (~/.claude/settings.json, environment variables, IDE settings).
4. Still unclear (for example a 403 whose message is not listed here): send Admin/IT the time and the last 8 characters of the key; they can find it in the gateway dashboard logs.