Lỗi 401 authentication_error / invalid x-api-key — cần kiểm tra gì, theo thứ tự

Hầu hết lỗi 401 đều có một trong bốn nguyên nhân, và chỉ một nguyên nhân là “khóa sai”. Ba nguyên nhân còn lại vẫn để khóa hoàn toàn hợp lệ — vì vậy tạo lại khóa thường là công sức lãng phí.

Lỗi

phản hồi (HTTP 401)

{
  "type": "error",
  "error": { "type": "authentication_error",
             "message": "invalid x-api-key" }
}

Tổng quan nguyên nhân và cách khắc phục

Nguyên nhân	Cách khắc phục
Tiêu đề không đúng với máy chủ	Anthropic đọc x-api-key; phần lớn gateway tương thích với OpenAI đọc Authorization: Bearer. Cùng một giá trị nhưng đặt trong tiêu đề sai sẽ được hiểu là bị thiếu.
Còn sót biến môi trường cũ	Một ANTHROPIC_API_KEY bị bỏ quên trong cấu hình shell có thể được ưu tiên hơn khóa bạn vừa export.
Đổi base URL nhưng không đổi thông tin xác thực	Trỏ sang một máy chủ khác không khiến khóa của nhà cung cấp trước đó hợp lệ tại đó. Máy chủ và thông tin xác thực phải thay đổi cùng nhau.
Khoảng trắng, xuống dòng hoặc dấu ngoặc kép trong khóa	Sao chép từ PDF hoặc cuộc trò chuyện thường mang theo ký tự ẩn. Hãy kiểm tra độ dài chuỗi.

Kiểm tra nội dung thực sự có trong môi trường

Trước khi thay đổi bất cứ điều gì, hãy xem các biến trong cùng shell đang chạy ứng dụng. Một phần đáng ngạc nhiên các trường hợp có đồng thời hai thông tin xác thực từ các nhà cung cấp khác nhau.

conferir.sh

for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s [%s] tamanho=%s\n' \
    "$v" "$(printenv "$v" | cut -c1-10)" "$(printenv "$v" | wc -c)"
done

Kiểm tra thông tin xác thực bên ngoài ứng dụng

Một yêu cầu trực tiếp giúp phân biệt “máy chủ từ chối khóa” với “ứng dụng không gửi khóa”. Nếu curl hoạt động còn mã nguồn không hoạt động, vấn đề không nằm ở thông tin xác thực.

testar.sh

curl -s -o /dev/null -w 'status=%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

# 200 -> credencial boa; investigue a aplicação
# 401 -> credencial ou cabeçalho errados para este host

Phân biệt 401 với 403 và 402

401 nghĩa là “không biết bạn là ai”: thông tin xác thực không được chấp nhận. 403 nghĩa là “biết bạn là ai nhưng bạn không được phép”: đã xác thực nhưng không có quyền. 402 nghĩa là “biết bạn là ai nhưng không đủ số dư”. Chỉ 401 được giải quyết bằng cách chỉnh thông tin xác thực.

Nếu bạn gọi qua Kunavo

Kunavo đọc khóa sk-kn- trong cả Authorization: Bearer và x-api-key, còn base URL là nguồn gốc của trang web, không có thêm đường dẫn nào phía sau. Với Claude Code, hãy dùng ANTHROPIC_AUTH_TOKEN cùng ANTHROPIC_BASE_URL, vì token không phụ thuộc vào cơ chế phê duyệt một lần mà ANTHROPIC_API_KEY yêu cầu; đồng thời xóa rõ ràng ANTHROPIC_API_KEY — giá trị cũ trong biến này là nguyên nhân phổ biến nhất khiến một phiên trông như đã được cấu hình nhưng vẫn bị từ chối. Quy trình từng bước về xác thực có trong tài liệu xác thực.

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

Tạo lại khóa có giải quyết được không?

Chỉ khi khóa thực sự đã bị thu hồi. Với ba nguyên nhân phổ biến còn lại — tiêu đề sai, biến cũ, base URL bị đổi — khóa mới cũng sẽ thất bại y hệt.

401 có thể là do không đủ số dư không?

Không. Số dư không đủ là 402, kèm thông báo nói về tín dụng. 401 luôn liên quan đến danh tính.

Hoạt động với curl nhưng thất bại trong mã của tôi. Vì sao?

Gần như luôn là do mã đọc một biến môi trường khác, hoặc chạy trong shell/container khác nơi lệnh export không được truyền tới. Hãy in thông tin xác thực đã che một phần ngay trong tiến trình để xác nhận.

Hướng dẫn liên quan

Thông tin chi tiết hơn về ý nghĩa lỗi có trong tài liệu tham chiếu lỗi; bạn chỉ mất một phút để lấy khóa qua đăng ký và hướng dẫn xác thực.