Claude API 401 authentication_error / invalid x-api-key

Claude의 401은 항상 다섯 가지 중 하나입니다. 잘못된 헤더, 엔드포인트에 맞지 않는 키 유형, 잘못된 환경 변수, 폐기된 키 또는 해당 키에 맞지 않는 base URL입니다. 아래 진단을 실행하면 1분 안에 원인을 찾을 수 있습니다.

오류

response (HTTP 401)

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

원인과 해결 방법 한눈에 보기

원인	해결 방법
엔드포인트에 잘못된 헤더	Anthropic 네이티브 API는 x-api-key + anthropic-version을 요구하며, OpenAI 호환 엔드포인트는 Authorization: Bearer를 요구합니다.
키와 엔드포인트 불일치	sk-ant-… 키는 api.anthropic.com에서만 작동하고, 게이트웨이 키(예: sk-kn-…)는 자체 게이트웨이 URL에서만 작동합니다.
환경 변수에 공백이나 따옴표가 포함됨	따옴표와 줄바꿈 없이 다시 내보내고, len(key)를 출력해 복사하여 붙여넣은 뒤의 \n을 확인하세요.
키가 폐기되었거나 워크스페이스가 비활성화됨	콘솔에서 새 키를 발급하고 시크릿 관리자에서 교체하세요.

원시 curl로 재현하세요(SDK를 문제에서 제외)

curl은 작동하지만 앱이 작동하지 않는다면 문제는 키가 아니라 환경 변수 연결입니다.

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))"

키 접두사와 base URL을 일치시키세요

sk-ant-… → api.anthropic.com. sk-kn-… → api.kunavo.com/v1. 게이트웨이 키를 Anthropic으로 보내거나 그 반대로 보내면 항상 401이 발생합니다. 오류 메시지는 "wrong host"라고 표시하지 않으므로 이 원인은 쉽게 지나칠 수 있습니다.

키가 저장소나 로그에 노출된 적이 있다면 교체하세요

키가 올바른데도 계속 거부된다면 폐기를 의심하세요(자동 스캐너는 유출된 키를 빠르게 폐기합니다). 새 키를 발급하고 커밋되는 .env 파일 대신 시크릿 관리자에 저장하세요.

Kunavo를 통해 호출하는 경우

Kunavo 키(sk-kn-…)는 모든 엔드포인트에서 두 헤더 중 어느 쪽으로도 인증됩니다. OpenAI SDK가 보내는 Authorization: Bearer 또는 Anthropic SDK가 사용하는 x-api-key를 사용할 수 있습니다. 따라서 어떤 SDK를 사용하든 변경되는 것은 base URL뿐입니다. 대시보드에서 키를 즉시 생성하고 폐기할 수 있습니다. 키가 인증되면 청구되는 요금은 다음 위치에 있습니다 Anthropic Claude API 가격표.

자주 묻는 질문

curl에서는 키가 작동하지만 앱에서는 작동하지 않는 이유는 무엇인가요?

거의 항상 환경 변수 연결 문제입니다. 복사하여 붙여넣은 뒤의 줄바꿈, 값에 포함된 따옴표, 프로세스에 변수를 내보내지 않은 경우, 프로덕션에서 다른 환경을 불러오는 경우가 원인일 수 있습니다. 실패하는 프로세스 내부에서 키의 repr과 길이를 출력하세요.

Anthropic Console 키를 OpenAI 호환 게이트웨이에서 사용할 수 있나요?

아니요. 각 서비스는 자체 키만 인증합니다. sk-ant 키는 api.anthropic.com에 속하고 게이트웨이 키는 게이트웨이에 속합니다. 호출하는 base URL에 해당하는 키를 받으세요.

오류 의미에 대한 자세한 내용은 오류 참조에서 확인할 수 있습니다. 가입 및 인증 가이드를 통해 1분이면 키를 받을 수 있습니다.

Claude API 401 authentication_error / invalid x-api-key — 모든 원인

오류