Các lỗi Claude Code và cách khắc phục

Hướng dẫn chi tiết cho từng lỗi

• Lỗi API: 500 (Lỗi máy chủ nội bộ) — sự cố gián đoạn, lỗi theo từng mô hình, nén ngữ cảnh ở 0%.
• Quá tải / Lỗi API 529 — năng lực phục vụ, thử lại, các đợt tăng đột biến tác nhân phụ.
• Lỗi API 400 — prompt quá dài, việc sử dụng công cụ đồng thời và các yêu cầu bị từ chối khác.
• Lỗi OAuth — vượt quá thời gian chờ 15000ms, mã trạng thái 500 khi đăng nhập.
• Tiến trình thoát với mã 1 — tiện ích mở rộng VS Code và ứng dụng máy tính bị lỗi và dừng.
• Đã đạt giới hạn tốc độ / 429 — ba loại giới hạn và cách tăng chúng.
• Prompt quá dài / đã đạt giới hạn ngữ cảnh — những gì làm đầy cửa sổ ngữ cảnh, cảnh báo sai, lỗi nén ngữ cảnh, giới hạn độ dài claude.ai.
• Đã đạt giới hạn sử dụng — các khoảng giới hạn theo phiên, theo tuần và của Opus, "giới hạn sử dụng API đã chỉ định", "số dư tín dụng quá thấp".
• Xác thực 401 / 403 — thông tin xác thực không hợp lệ, khóa API không hợp lệ, "Chưa đăng nhập", host_not_allowed.
• Lỗi kết nối — ECONNRESET, "Đang chờ phản hồi API", chứng chỉ, proxy, các biến cấu hình thử lại.
• Treo, mắc kẹt, không phản hồi — vị trí bị kẹt, các phím thoát, lỗi treo đã biết, bộ nhớ.
• claude.ai không hoạt động — "Đã xảy ra lỗi", hạn chế năng lực phục vụ, giới hạn 5 giờ, lỗi đăng nhập.

Lỗi API 500 (và 529 quá tải)

500 là lỗi từ upstream; 529 là mã mà Anthropic dùng để báo rõ "mô hình đã đạt giới hạn năng lực phục vụ". Cả hai đều không do prompt của bạn gây ra. Claude Code tự thử lại vài lần; nếu ngừng thử, hãy đợi một phút rồi tiếp tục bằng claude -c. Chuyển cấp mô hình bằng /model thường có hiệu quả ngay vì năng lực phục vụ được phân bổ theo từng mô hình. Trên gateway này, khi một tài khoản upstream quá tải, hệ thống tự động chuyển sang tài khoản khác, nên lỗi 529 ở đây ít gặp hơn so với khi dùng một tài khoản duy nhất.

Lỗi API 400 — yêu cầu không hợp lệ / ngữ cảnh quá dài

Trong Claude Code, 400 gần như luôn có nghĩa là cuộc hội thoại cùng các tệp đã đọc không còn vừa với cửa sổ ngữ cảnh của mô hình. /compact tóm tắt lịch sử; /clear bắt đầu lại từ đầu; hoặc chuyển sang một (1M) biến thể của mô hình. Các lỗi 400 khác: tham số không được hỗ trợ sau khi nâng cấp (chạy claude update), hoặc hình ảnh hay tệp mà mô hình không thể tiếp nhận.

Lỗi API 429 — giới hạn tốc độ / vượt quá tốc độ cho phép

Có ba giới hạn: số yêu cầu mỗi phút, số token mỗi phút và số yêu cầu đồng thời. Các phiên tác nhân chạm giới hạn đồng thời trước tiên — mỗi tác nhân phụ là một yêu cầu truyền luồng song song, chiếm một vị trí cho đến khi hoàn tất. Giảm mức độ song song, chờ hết khoảng retry-after và, nếu cần làm việc liên tục, hãy yêu cầu tăng giới hạn đồng thời cho tài khoản gateway của bạn.

Lỗi OAuth: vượt quá thời gian chờ 15000ms

Luồng /login không thể kết nối đến dịch vụ xác thực của Anthropic trong 15 giây. Đây là vấn đề mạng, không phải tài khoản: proxy doanh nghiệp, VPN làm mất callback hoặc khu vực mà endpoint xác thực phản hồi chậm. Thử lại một lần; nếu vẫn xảy ra, đặt HTTPS_PROXY cho mạng của bạn, hoặc bỏ qua OAuth hoàn toàn bằng cách dùng khóa API — với ANTHROPIC_API_KEY (và ANTHROPIC_BASE_URL nếu dùng gateway), Claude Code sẽ không mở luồng đăng nhập.

Lỗi OAuth: yêu cầu thất bại với mã trạng thái 500

Dịch vụ xác thực trả về lỗi máy chủ khi đăng nhập hoặc làm mới token. Lỗi này không do phía bạn gây ra; hãy đợi vài phút rồi chạy lại /login. Nếu cần làm việc ngay, cách dùng khóa API ở trên bỏ qua OAuth, và claude setup-token trên máy đăng nhập được sẽ tạo ra token có thời hạn dài mà bạn có thể chuyển sang máy không đăng nhập được.

Lỗi: tiến trình Claude Code thoát với mã 1

Đây là tiện ích mở rộng IDE hoặc ứng dụng máy tính báo rằng CLI mà nó khởi chạy đã gặp lỗi ngay lúc khởi động — lỗi thực sự nằm ở tầng bên dưới. Mở terminal và chạy claude trực tiếp: bạn sẽ thấy thông báo thực tế, gần như luôn là phiên bản Node.js thấp hơn 18, PATH bị hỏng sau khi cài qua npm, bản cài đặt gốc bị hỏng hoặc settings.json chứa JSON không hợp lệ (dấu phẩy thừa trong khối hooks là trường hợp điển hình). claude doctor kiểm tra ba nguyên nhân đầu; công cụ kiểm tra cú pháp JSON phát hiện nguyên nhân thứ tư. Cài lại bằng trình cài đặt gốc khắc phục phần lớn các trường hợp còn lại.

401 / lỗi xác thực

invalid x-api-key hoặc authentication_error có nghĩa là khóa không thuộc endpoint. Nếu ANTHROPIC_BASE_URL trỏ đến gateway, khóa phải là khóa gateway; khóa console của Anthropic sẽ bị từ chối, và ngược lại cũng vậy. /status cho biết endpoint và khóa nào đang được sử dụng. Nếu bạn dùng /login và khóa API cùng lúc, khóa API được ưu tiên. Các vòng lặp làm mới token, Not logged in sau khi đăng nhập thành công và lỗi 403 từ proxy được trình bày trên trang 401 / 403.

"Không có upstream hoạt động"

Đây không phải lỗi API: bộ cân bằng tải phía trước dịch vụ đang báo rằng không có backend nào khả dụng. Với endpoint chính thức, điều này có nghĩa là dịch vụ bị gián đoạn; với gateway, nó có nghĩa là toàn bộ nhóm upstream đang ngừng hoạt động hoặc bị hạn chế lưu lượng. Hãy đợi rồi thử lại; đừng thay đổi cấu hình.

Claude Code hoàn toàn không hoạt động

• Khởi động rồi thoát mà không báo gì → chạy claude /doctor; thường là vấn đề phiên bản Node hoặc PATH.
• Treo khi khởi động hoặc giữa phiên → xem tình trạng treo và phiên bị kẹt và lỗi kết nối.
• command not found → xem hướng dẫn cài đặt.
• Công cụ thất bại do lỗi quyền truy cập → /permissions, hoặc --allowedTools trong script.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Câu hỏi thường gặp

AI Prime Tech là một cổng API độc lập, không có quan hệ liên kết với Anthropic và không được Anthropic chứng thực hay tài trợ. “Claude” và “Claude Code” là các nhãn hiệu của Anthropic. Các tính năng Claude Code được mô tả ở đây dựa trên tài liệu công khai của Anthropic tại thời điểm viết và thường xuyên thay đổi; giá và danh sách mô hình trên trang này được đọc từ cấu hình hiện hành của cổng API này.