Xử lý sự cố

Một request đi qua ba chặng, mỗi chặng có kiểu lỗi riêng:

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

Nguồn	Dấu hiệu nhận biết
sotatek-proxy	Body {"error":"upstream unreachable","proxy":"sotatek-proxy"} (HTTP 502), hoặc response có header X-Git-Remote-Warning
Gateway	Body {"error":{"message":...}}. Lỗi governance có thêm "type" (ví dụ virtual_key_blocked); các lỗi 403 ở mục 2.1–2.4 chỉ có message
Provider	Message/type gốc của provider, thường giữ nguyên HTTP status của provider

Khi báo lỗi cho Admin/IT

Hãy gửi thời điểm xảy ra và 8 ký tự cuối của key. Tuyệt đối không gửi toàn bộ key.

1. Lỗi từ sotatek-proxy

Connection refused

Proxy chưa chạy. Kiểm tra bằng sotatek-proxy status, khởi động bằng sotatek-proxy start, và đảm bảo CLI trỏ đúng ANTHROPIC_BASE_URL=http://127.0.0.1:3817/anthropic.

HTTP 502 upstream unreachable

Proxy không nối được tới gateway (mạng, VPN, DNS hoặc gateway down). Kiểm tra mạng/VPN rồi xem sotatek-proxy logs. Nếu mạng ổn mà vẫn lỗi, liên hệ Admin/IT.

Header X-Git-Remote-Warning / X-Git-Remote-Remedy

Khi không xác định được git remote, proxy vẫn forward request và báo nguyên nhân qua hai header ở response này. Sau đó gateway có thể từ chối bằng lỗi 403 ở mục 2.1 hoặc 2.2. Hãy chạy sotatek-proxy doctor từ repo đang bị lỗi để xem nguyên nhân và cách sửa.

Mã nguyên nhân	Ý nghĩa	Cách xử lý
not_a_repo	CLI được mở ngoài git repo (proxy quét tối đa 3 cấp thư mục cha)	Mở lại CLI từ bên trong repo
no_remote	Repo chưa có remote	git remote add origin <url>
git_not_found	Service không tìm thấy git	macOS: xcode-select --install (git Homebrew cần symlink vào /usr/local/bin vì launchd chỉ thấy PATH tối thiểu). Windows: cài Git for Windows rồi restart service. Linux: cài git rồi restart service
git_shim_broken	/usr/bin/git trên macOS chỉ là stub qua xcrun, hỏng sau khi nâng cấp OS	xcode-select --install
git_ownership	git từ chối repo thuộc user khác	git config --global --add safe.directory <đường dẫn repo>
git_permission	Proxy không đọc được repo	Kiểm tra owner/quyền của repo và user chạy service
git_timeout	git remote -v chạy quá 2s (network drive, credential helper treo)	Đo thời gian git remote -v trong repo đó
git_exec_failed	git lỗi vì lý do khác	Chạy git remote -v thủ công để xem lỗi gốc
pid_not_found, cwd_not_found	Process client đã thoát trước khi kịp kiểm tra	Thỉnh thoảng gặp thì bỏ qua; gặp liên tục thì chạy sotatek-proxy doctor
inspect_timeout, inspect_failed	Công cụ dò process (lsof, /proc, bảng TCP Windows) lỗi hoặc quá hạn	Chạy sotatek-proxy doctor và làm theo gợi ý theo hệ điều hành
non_loopback_peer	Client không kết nối qua loopback	Dùng http://127.0.0.1:3817

2. Lỗi từ gateway

Gateway kiểm tra theo thứ tự: xác thực key → git context → git/project guard → project model guard → governance (trạng thái key, budget, rate limit).

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

• Nguyên nhân: request không có header X-Git-Remote (gọi thẳng gateway, hoặc proxy không xác định được remote — xem phần trên). Gateway mặc định bắt buộc header này, trừ key được Admin bật bypass_git_guard.
• Bạn làm: đi qua sotatek-proxy, không gọi thẳng gateway; chạy sotatek-proxy doctor trong repo.
• Liên hệ Admin/IT khi cần bypass_git_guard cho CI/script, hoặc proxy chạy bình thường mà vẫn lỗi.

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

• Nguyên nhân: có X-Git-Remote nhưng base64 sai hoặc rỗng.
• Bạn làm: restart proxy (sotatek-proxy stop rồi start), đảm bảo không công cụ nào khác tự thêm header này.
• Header hợp lệ nhưng nội dung không có remote dùng được thì không bị từ chối; request chỉ không được gắn project.

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

• Nguyên nhân: git remote của repo đã được Admin gán cho project A, nhưng key bạn dùng thuộc project B.
• Bạn làm: dùng đúng key của project đang làm việc, hoặc xin key đúng project.
• Liên hệ Admin/IT nếu key đúng mà vẫn lỗi — repo có thể bị gán nhầm project hoặc key bị tag sai. Gateway bỏ qua kiểm tra này nếu repo chưa được gán project hoặc key chưa gắn project.

2.4 403 — requested model is not permitted

• Nguyên nhân: project của repo có danh sách model được phép và model bạn gọi không nằm trong đó. Message cố ý không nêu tên project.
• Bạn làm: đổi model. Admin/IT có thể thêm model cho project.

2.5 403 virtual_key_blocked — Virtual key is inactive

• Nguyên nhân: key bị Admin tắt.
• Hãy kiểm tra trước — có thể bạn đang gửi nhầm key. Claude Code đọc key từ biến môi trường và ~/.claude/settings.json; VS Code và Antigravity có cấu hình riêng. Xung đột giữa chúng không tự gây lỗi này, nhưng nếu tool gửi một key cũ hoặc đã bị tắt thì sẽ gặp lỗi. Hãy kiểm tra:
  1. ANTHROPIC_AUTH_TOKEN trong mục env của ~/.claude/settings.json và trong biến môi trường của shell.
  2. Key cấu hình trong VS Code (xem VS Code) và Antigravity (xem Antigravity).
  3. Thống nhất một key hợp lệ duy nhất rồi khởi động lại CLI/IDE.
• Liên hệ Admin/IT nếu chắc chắn key đang gửi chính là key bạn được cấp.

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

Thời điểm hiện tại (UTC) đã qua end_date hoặc chưa tới start_date của key. Nhờ Admin/IT gia hạn hoặc xác nhận ngày hiệu lực.

2.7 403 virtual_key_not_found — Virtual key not found

Key (sk-bf-...) không tồn tại: gõ sai, copy thiếu ký tự, hoặc đã bị xoá. Copy lại cẩn thận; nếu vẫn lỗi, nhờ Admin/IT cấp lại.

2.8 401 virtual_key_required

• Message: virtual key is required. Provide a virtual key via the x-bf-vk header.
• Nguyên nhân: gateway bắt buộc virtual key và request không có key hợp lệ. Key được nhận từ x-bf-vk, Authorization: Bearer, x-api-key hoặc x-goog-api-key và phải bắt đầu bằng sk-bf-; key sai tiền tố bị coi như không có key.
• Bạn làm: kiểm tra ANTHROPIC_AUTH_TOKEN đã được đặt và đúng định dạng.

2.9 401 Unauthorized / invalid_admin_api_key / 403 forbidden_for_api_key_actor

Ít gặp với user thường. Thường do dùng key quản trị (bfak_*) cho route gọi model, hoặc gateway yêu cầu thêm credential. Hãy dùng virtual key sk-bf-...; nếu vẫn lỗi, liên hệ 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. Khác mục 2.4, giới hạn này theo key, không theo project. Đổi model/provider, hoặc nhờ Admin/IT sửa danh sách cho phép của key.

2.11 429 rate_limited / token_limited / request_limited

Ví dụ: rate limit violated for <name>: [token limit exceeded (used/max, resets every <window>)]. Chờ tới lúc reset ghi trong message và giảm tần suất gọi. Nhờ Admin/IT nâng giới hạn nếu cần.

2.12 402 budget_exceeded

<scope> budget exceeded: <used> >= <max> dollars (scope: key, team, customer, provider hoặc model). Bạn không tự xử lý được — liên hệ Admin/IT, hoặc chờ sang chu kỳ reset.

2.13 429 user_budget_exceeded

user budget exceeded — contact administrator. Budget tính theo chủ sở hữu key. Liên hệ Admin/IT hoặc chờ reset.

2.14 400 missing_required_headers

missing required headers: <list>. Chỉ xuất hiện khi Admin cấu hình header bắt buộc. Hỏi Admin/IT cần gửi header nào.

3. Lỗi từ provider

Lỗi 4xx/5xx của provider (key provider sai, upstream rate limit, 5xx, 529 overloaded) được gateway chuyển tiếp kèm message gốc, thường giữ nguyên HTTP status. Với 429/5xx/529, hãy thử lại sau; nếu kéo dài, báo Admin/IT kèm thời điểm.

Chẩn đoán nhanh

1. Xem HTTP status và body để phân biệt lỗi proxy, gateway hay provider.
2. Với lỗi 403 liên quan git (2.1–2.3), chạy sotatek-proxy doctor trong repo đang lỗi.
3. Với lỗi key (2.5–2.8), kiểm tra key thực sự đang được gửi (~/.claude/settings.json, biến môi trường, cấu hình IDE).
4. Vẫn chưa rõ (ví dụ 403 với message không có trong trang này): gửi Admin/IT thời điểm và 8 ký tự cuối của key; họ có thể tra log trên dashboard gateway.