Claude API 401 authentication_error / invalid x-api-key

Mã 401 từ Claude luôn thuộc một trong năm nguyên nhân: sai tiêu đề, sai loại khóa đối với endpoint, biến môi trường sai định dạng, khóa bị thu hồi hoặc base URL không đúng với khóa đó. Chạy chẩn đoán bên dưới và bạn sẽ tìm ra nguyên nhân trong chưa đầy một phút.

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
Header không đúng cho endpoint	API gốc của Anthropic yêu cầu x-api-key + anthropic-version; các endpoint tương thích OpenAI yêu cầu Authorization: Bearer.
Khóa và endpoint không khớp	Các khóa sk-ant-… chỉ hoạt động với api.anthropic.com; khóa gateway (ví dụ sk-kn-…) chỉ hoạt động với URL gateway tương ứng.
Biến môi trường chứa khoảng trắng hoặc dấu ngoặc kép ngoài ý muốn	Xuất lại biến mà không có dấu ngoặc kép hoặc ký tự xuống dòng; in len(key) để phát hiện \n ở cuối do sao chép-dán.
Khóa đã bị thu hồi hoặc workspace bị vô hiệu hóa	Tạo khóa mới trong console và xoay khóa trong trình quản lý secret.

Tái hiện bằng curl thô (loại SDK của bạn khỏi phương trình)

Nếu curl hoạt động nhưng ứng dụng không hoạt động, lỗi nằm ở việc truyền biến môi trường, không phải khóa:

diagnose.sh

# Native Anthropic wire (works on api.anthropic.com and Kunavo /v1/messages)
curl -s https://api.kunavo.com/v1/messages \
  -H "x-api-key: $KUNAVO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# OpenAI-compatible wire (Bearer header instead)
curl -s https://api.kunavo.com/v1/chat/completions \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Check the key isn't carrying whitespace
python3 -c "import os; k=os.environ['KUNAVO_API_KEY']; print(repr(k[:12]), len(k))"

Đối chiếu tiền tố khóa với base URL

sk-ant-… → api.anthropic.com. sk-kn-… → api.kunavo.com/v1. Gửi khóa gateway đến Anthropic (hoặc ngược lại) luôn trả về 401 — thông báo lỗi không bao giờ nói "wrong host", nên lỗi này dễ bị bỏ sót.

Xoay khóa nếu khóa từng xuất hiện trong repo hoặc log

Nếu khóa đúng nhưng vẫn bị từ chối, hãy giả định khóa đã bị thu hồi (các trình quét tự động nhanh chóng thu hồi khóa bị lộ). Tạo khóa mới và lưu trong trình quản lý secret thay vì các tệp .env có thể bị commit.

Nếu bạn gọi qua Kunavo

Các khóa Kunavo (sk-kn-…) xác thực bằng cả hai header trên mọi endpoint — Authorization: Bearer như OpenAI SDK gửi, hoặc x-api-key như Anthropic SDK gửi — vì vậy dù dùng SDK nào, bạn chỉ cần thay đổi base URL. Khóa được tạo và thu hồi ngay lập tức trong dashboard. Sau khi khóa xác thực, mức giá được tính cho bạn nằm trong bảng giá Anthropic Claude API.

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

Tại sao khóa của tôi hoạt động trong curl nhưng không hoạt động trong ứng dụng?

Gần như luôn là vấn đề truyền biến môi trường: ký tự xuống dòng ở cuối do sao chép-dán, giá trị bao gồm dấu ngoặc kép, biến chưa được export vào tiến trình, hoặc môi trường khác được nạp trong production. In repr và độ dài của khóa bên trong tiến trình bị lỗi.

Tôi có thể dùng khóa Anthropic Console trên gateway tương thích OpenAI không?

Không. Mỗi dịch vụ chỉ xác thực khóa của chính dịch vụ đó: khóa sk-ant thuộc api.anthropic.com, còn khóa gateway thuộc gateway. Hãy lấy khóa từ base URL mà bạn đang gọi.

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.

Claude API 401 authentication_error / invalid x-api-key — mọi nguyên nhân

Lỗi