Error 401 authentication_error / invalid x-api-key — apa yang harus diperiksa, secara berurutan

Hampir semua error 401 memiliki salah satu dari empat penyebab, dan hanya satu di antaranya adalah "kuncinya salah". Tiga penyebab lainnya dapat membuat kunci yang sepenuhnya valid tetap ditolak — itulah sebabnya membuat ulang kunci biasanya membuang-buang usaha.

Error

respons (HTTP 401)

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

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
Header salah untuk host tersebut	Anthropic membaca x-api-key; sebagian besar gateway yang kompatibel dengan OpenAI membaca Authorization: Bearer. Nilai yang sama pada header yang salah akan diterima seolah-olah tidak ada.
Variabel lingkungan lama yang tertinggal	ANTHROPIC_API_KEY yang terlupakan di profil shell dapat mengalahkan kunci yang baru saja Anda export.
Base URL diganti tanpa mengganti kredensial	Mengarahkan ke host lain tidak membuat kunci dari penyedia sebelumnya menjadi valid di sana. Host dan kredensial harus diganti bersama-sama.
Spasi, baris baru, atau tanda kutip dalam kunci	Menyalin dari PDF atau chat sering membawa karakter tak terlihat. Periksa panjang string tersebut.

Periksa isi sebenarnya dari lingkungan

Sebelum mengubah apa pun, lihat variabel di shell yang sama dengan shell yang menjalankan aplikasi. Dalam jumlah kasus yang mengejutkan, dua kredensial dari penyedia berbeda ditetapkan secara bersamaan.

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

Uji kredensial di luar aplikasi

Permintaan langsung membedakan antara "host menolak kunci" dan "aplikasi tidak mengirim kunci". Jika curl berhasil tetapi kode gagal, masalahnya bukan kredensial.

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

Bedakan 401 dari 403 dan 402

401 berarti "saya tidak tahu siapa Anda": kredensial tidak diterima. 403 berarti "saya tahu siapa Anda, tetapi Anda tidak diizinkan": sudah terautentikasi, tanpa izin. 402 berarti "saya tahu siapa Anda, tetapi saldo tidak mencukupi". Hanya 401 yang diselesaikan dengan mengubah kredensial.

Jika Anda melakukan panggilan melalui Kunavo

Kunavo membaca kunci sk-kn- baik melalui Authorization: Bearer maupun x-api-key, dan base URL adalah origin situs tanpa path apa pun setelahnya. Dengan Claude Code, gunakan ANTHROPIC_AUTH_TOKEN bersama ANTHROPIC_BASE_URL, karena token tersebut tidak bergantung pada persetujuan satu kali yang diwajibkan ANTHROPIC_API_KEY, lalu hapus ANTHROPIC_API_KEY secara eksplisit — nilai lama dalam variabel ini adalah penyebab paling umum sesi tampak sudah dikonfigurasi tetapi tetap menolak permintaan. Panduan autentikasi langkah demi langkah tersedia di dokumentasi autentikasi.

Pertanyaan umum

Apakah membuat ulang kunci akan menyelesaikan masalah?

Hanya jika kuncinya memang telah dicabut. Pada tiga penyebab umum lainnya — header salah, variabel lama, dan base URL yang diganti — kunci baru akan gagal dengan cara yang sama persis.

Apakah 401 bisa disebabkan oleh saldo yang tidak mencukupi?

Tidak. Saldo tidak mencukupi menghasilkan 402, dengan pesan yang menyebutkan kredit. 401 selalu berkaitan dengan identitas.

Berhasil dengan curl tetapi gagal di kode saya. Mengapa?

Hampir selalu karena kode membaca variabel lingkungan yang berbeda, atau berjalan di shell/container lain tempat export tidak diteruskan. Cetak kredensial yang telah disamarkan dari dalam proses untuk memastikannya.

Panduan terkait

Detail semantik error lainnya tersedia di referensi error; mendapatkan kunci hanya perlu satu menit melalui pendaftaran dan panduan autentikasi.