Tổng hợp lỗi Claude Code — cách phân biệt 401, 429, 529 và lỗi cài đặt

Lỗi Claude Code có hai nhóm lớn, và phần lớn kết quả tìm kiếm chỉ đề cập một nhóm. Lỗi client ở giai đoạn cài đặt·chạy và lỗi API trả về khi gọi mô hình có nguyên nhân cũng như cách xử lý hoàn toàn khác nhau. Bài viết này tập trung vào nhóm thứ hai — 401, 429, 529 — vì đây là những lỗi đầu tiên thường gặp khi chuyển từ gói đăng ký sang khóa API.

Chuỗi lỗi xuất hiện bằng tiếng Anh ở mọi quốc gia. Dưới đây, chúng tôi giữ nguyên chuỗi và chỉ giải thích bằng tiếng Việt.

Trước tiên, chia nguyên nhân thành ba nhóm trong 30 giây

Trước khi thay đổi cài đặt, hãy gửi một yêu cầu trực tiếp đến endpoint. Chỉ một lần này sẽ phân biệt “vấn đề client / vấn đề xác thực / vấn đề server”.

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

401 — header sai, không phải khóa sai

Nếu liên tục nhận 401 dù đã cấp khóa mới nhiều lần, hãy nghi ngờ cách gửi chứ không phải giá trị khóa. Claude Code gửi ANTHROPIC_AUTH_TOKEN trong header Authorization: Bearer, còn ANTHROPIC_API_KEY trong header x-api-key. Gateway thường chờ loại thứ nhất, vì vậy hoán đổi hai biến sẽ gây 401 dù khóa hợp lệ.

Cũng thường xảy ra trường hợp cả hai biến cùng tồn tại. Hãy xóa một biến, mở shell mới rồi thử lại. Sự khác nhau giữa từng biến được trình bày trong sự khác nhau giữa ANTHROPIC_AUTH_TOKEN và ANTHROPIC_API_KEY.

429 — hai loại 429 hoàn toàn khác nhau

Cùng một con số nhưng nguyên nhân hoàn toàn khác. Nếu đang dùng gói đăng ký, bạn đã chạm giới hạn cửa sổ phiên và không có cách nào ngoài chờ cửa sổ được đặt lại — nâng lên gói cao hơn cũng không giúp ích tại thời điểm đó. Nếu đang dùng khóa API, đó là giới hạn số yêu cầu mỗi giây hoặc thông lượng token và hầu hết trường hợp có thể giải quyết bằng thử lại với exponential backoff.

Có thể phân biệt ngay bằng việc ANTHROPIC_BASE_URL có được đặt hay không. Nếu được đặt, bạn đang dùng khóa chứ không phải gói đăng ký. Cấu trúc giới hạn gói đăng ký và các lựa chọn khi vượt giới hạn được trình bày trong giá Claude Code.

529 overloaded_error — lỗi không phải do tôi

529 có nghĩa là máy chủ mô hình thượng nguồn tạm thời quá tải. Nội dung yêu cầu, khóa và số dư đều không phải nguyên nhân, nên đây không phải lỗi có thể loại bỏ bằng cách sửa cài đặt. Cách xử lý là thử lại, và exponential backoff có tỷ lệ thành công cao hơn nhiều so với thử lại ngay lập tức.

Khi đi qua gateway có fallback tự động, nếu một thượng nguồn trả về 529, yêu cầu sẽ chuyển sang đường khác, giúp giảm tần suất lỗi thực tế. Bản giải thích chi tiết dành cho độc giả tiếng Anh có tại cách xử lý 529 overloaded_error.

Tiếp tục làm việc khi chạm giới hạn gói đăng ký

Nếu 429 đến từ gói đăng ký, bạn có thể chuyển riêng phiên đó sang khóa thay vì chờ. Không cần hủy gói đăng ký — chỉ trong thời gian hai biến dưới đây được đặt, phí mới tính theo khóa; xóa chúng để quay lại như cũ.

# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 가리키므로,
# Kunavo가 아직 제공하지 않는 모델이 호출돼 404가 나지 않도록 모델을 고정합니다.
# sonnet 별칭이 부르는 Sonnet 5.5는 Kunavo가 제공하지 않아, 고정하지 않으면
# /model sonnet, opusplan의 실행 단계, sonnet으로 지정한 서브에이전트에서 404가 납니다.
# Opus 5.5는 Claude Code v2.1.280 이상이 필요합니다(이전 버전이면 claude update로 업데이트).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# haiku 별칭도 고정합니다. 고정하지 않으면 Kunavo가 제공하지 않는 모델 ID(v2.1.293부터
# Haiku 5.5)를 호출해 /model haiku와 haiku로 지정한 서브에이전트에서 404가 납니다.
# 같은 줄이 백그라운드 작업도 메인 모델 대신 Haiku로 보냅니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Mức giá được đọc trực tiếp từ danh mục: Claude Sonnet 5 là $1,40 / $7,00 cho mỗi 1M token, còn Claude Haiku 4.5 là $0,70 / $3,50. Phí được trừ từ số dư trả trước nên tháng không làm việc sẽ không phát sinh chi phí. Phương thức thanh toán và cách đăng ký thẻ nội địa được trình bày trong giá và thanh toán Claude API.

Lỗi ở bước cài đặt là vấn đề riêng

Vấn đề không cài đặt được phần lớn do phiên bản Node.js hoặc quyền cài đặt toàn cục, thuộc nhóm khác với ba lỗi trên. Trước tiên, hãy kiểm tra xem claude --version có hiển thị bình thường không. Nếu có, cài đặt đã hoàn tất và vấn đề sau đó nằm ở xác thực hoặc mạng. Trộn lẫn hai nhóm lỗi sẽ khiến bạn mất nhiều thời gian nhất.

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