Lỗi Claude Code thường gặp và cách sửa: API Error 401, 429, 529, hết hạn mức

Đọc thông báo lỗi trước khi sửa

Claude Code in lỗi theo dạng “API Error” kèm mã HTTP, hoặc một câu ngắn có dấu chấm giữa chỉ cách sửa. Hai lệnh giúp khoanh vùng nhanh: /status cho biết phiên đang xác thực bằng gì và gọi tới base URL nào, claude doctor kiểm tra bản cài đặt. Chép nguyên văn thông báo rồi đối chiếu với các mục dưới.

Lỗi đăng nhập và xác thực

Nhóm lỗi hay gặp khi mới cài hoặc khi đổi cách trả tiền:

• “Not logged in · Please run /login” hoặc “Login expired · Please run /login”: phiên đăng nhập chưa có hoặc đã hết hạn; chạy /login.
• “Invalid API key · Fix external API key”: key trong biến ANTHROPIC_API_KEY sai hoặc đã bị thu hồi; sửa hoặc bỏ biến đó.
• Cảnh báo kết thúc bằng “auth may not work as expected” (bản cũ ghi “Auth conflict: Both a token and an API key are set”): máy vừa có phiên đăng nhập vừa có key trong biến môi trường. Bỏ biến môi trường nếu muốn dùng gói thuê bao, hoặc chạy /logout nếu muốn dùng key.
• “Your organization has disabled Claude subscription access for Claude Code”: tổ chức đã tắt đăng nhập bằng gói thuê bao; xem bài sửa lỗi organization has disabled.

Lỗi hạn mức và giới hạn tốc độ

Nhóm lỗi xuất hiện khi đã dùng nhiều trong một khoảng thời gian:

• “You've hit your session limit · resets …”: hết hạn mức phiên 5 giờ của gói thuê bao; chờ tới giờ ghi trong thông báo hoặc xem các cách chạy tiếp ở bài Claude Code hết hạn mức.
• “API Error: Request rejected (429)”: vượt giới hạn tốc độ gọi. Đợi một lúc rồi thử lại; kiểm /status xem có biến ANTHROPIC_API_KEY nào đang vô tình được dùng thay cho gói thuê bao.
• “Credit balance is too low”: key của Claude Console đã hết tiền nạp, hoặc một API key đang ghi đè phiên đăng nhập gói thuê bao mà bạn định dùng.

Lỗi phía máy chủ: 500, 529 Overloaded

“API Error: Repeated 529 Overloaded errors” nghĩa là hệ thống của nhà cung cấp đang quá tải chung cho mọi người dùng, không phải bạn hết hạn mức. Claude Code tự thử lại vài lần; nếu vẫn lỗi, đợi vài phút hoặc chuyển tạm sang model khác bằng /model.

Lỗi 500 cũng là lỗi phía máy chủ và thường hết sau khi thử lại. Không cần đổi cấu hình hay cài lại khi gặp hai mã này.

Lỗi ngữ cảnh: Prompt is too long

Khi ngữ cảnh của phiên vượt giới hạn của model, Claude Code báo “Context limit reached · /compact or /clear to continue” (thông báo gốc từ API là “Prompt is too long”). Chạy /compact để tóm gọn phiên mà giữ mạch làm việc, hoặc /clear để bắt đầu sạch khi chuyển sang việc khác. Lệnh /context cho biết phần nào đang chiếm nhiều ngữ cảnh.

Lỗi cài đặt và phiên bản

Nhóm lỗi nằm ở chính bản Claude Code trên máy:

• “command not found: claude”: thư mục chứa lệnh chưa có trong PATH. Với bộ cài native, thêm ~/.local/bin vào PATH rồi mở terminal mới.
• “API Error: 400 … does not support this model”: bản Claude Code quá cũ so với model đang chọn; chạy claude update.
• Trên Windows không tìm thấy Git Bash: Claude Code dùng PowerShell khi không có Git for Windows; nếu đã cài Git ở chỗ khác, đặt biến CLAUDE_CODE_GIT_BASH_PATH.

Lỗi khi dùng Claude Code qua gateway

Khi Claude Code gọi qua một gateway bằng ANTHROPIC_BASE_URL, mã lỗi do gateway trả về. Với STEYG Code:

• 401 authentication_error: key sai, đã bị xoá, hoặc biến ANTHROPIC_AUTH_TOKEN chưa có trong phiên đang chạy.
• “Requested model … is not available in STEYG Code”: Claude Code gửi một model id không có trong danh mục, thường do alias chưa được gán; gán đủ các biến ANTHROPIC_DEFAULT_..._MODEL như bài dùng Claude Code với API key riêng.
• 402: ngân sách trả trước đã hết; gateway dừng nhận request mới thay vì tính vượt. Mua thêm ngân sách thì key cũ chạy tiếp.
• 429 kèm Retry-After: nguồn model yêu cầu chờ; Claude Code tự thử lại theo thời gian đó.
• Lỗi 5xx kéo dài: xem tình trạng từng model ở trang tình trạng hệ thống trước khi đổi cấu hình.

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