오류 401 authentication_error / invalid x-api-key — 순서대로 확인할 사항

거의 모든 401은 네 가지 원인 중 하나이며, 그중 하나만 ‘키가 잘못됨’입니다. 나머지 세 가지에서도 키 자체는 완전히 유효할 수 있으므로 키를 다시 만드는 것은 대개 헛수고입니다.

오류

resposta (HTTP 401)

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

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

원인	해결 방법
호스트에 맞지 않는 헤더	Anthropic은 x-api-key를 읽고, 대부분의 OpenAI 호환 게이트웨이는 Authorization: Bearer를 읽습니다. 헤더가 잘못되면 같은 값도 없는 것처럼 전달됩니다.
남아 있는 오래된 환경 변수	셸 프로필에 잊고 있던 ANTHROPIC_API_KEY가 방금 export한 값보다 우선할 수 있습니다.
자격 증명을 바꾸지 않고 Base URL만 변경	다른 호스트를 가리킨다고 이전 공급업체의 키가 그곳에서 유효해지는 것은 아닙니다. 호스트와 자격 증명은 함께 바뀌어야 합니다.
키에 포함된 공백, 줄바꿈 또는 따옴표	PDF나 채팅에서 복사하면 보이지 않는 문자가 들어오는 경우가 많습니다. 문자열 길이를 확인하세요.

환경에 실제로 들어 있는 값을 확인하세요

무엇이든 바꾸기 전에 애플리케이션을 실행하는 동일한 셸에서 변수를 확인하세요. 놀랍게도 많은 경우 서로 다른 공급업체의 자격 증명이 동시에 두 개 설정되어 있습니다.

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

애플리케이션 밖에서 자격 증명을 테스트하세요

직접 요청하면 ‘호스트가 키를 거부하는지’와 ‘애플리케이션이 키를 보내지 않는지’를 분리할 수 있습니다. curl은 작동하고 코드만 실패한다면 문제는 자격 증명이 아닙니다.

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

401, 403, 402를 구분하세요

401은 ‘당신이 누구인지 모르겠다’는 뜻으로 자격 증명이 승인되지 않은 상태입니다. 403은 ‘당신이 누구인지는 알지만 권한이 없다’는 뜻입니다. 402는 ‘당신이 누구인지는 알지만 잔액이 부족하다’는 뜻입니다. 자격 증명을 수정해서 해결되는 것은 401뿐입니다.

Kunavo를 통해 호출하는 경우

Kunavo는 Authorization: Bearer와 x-api-key 모두에서 sk-kn- 키를 읽으며, base URL은 뒤에 경로가 없는 사이트의 원본입니다. Claude Code에서는 ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_BASE_URL을 사용하세요. 토큰은 ANTHROPIC_API_KEY에 필요한 일회성 승인에 의존하지 않기 때문입니다. 또한 ANTHROPIC_API_KEY를 명시적으로 제거하세요 — 이 변수의 오래된 값이 설정된 것처럼 보이는데도 세션이 거부되는 가장 흔한 원인입니다. 인증 단계별 안내는 인증 문서.

자주 묻는 질문

키를 다시 만들면 해결되나요?

키가 실제로 폐기된 경우에만 그렇습니다. 가장 흔한 나머지 세 가지 원인인 잘못된 헤더, 오래된 변수, 변경된 base URL에서는 새 키도 똑같이 실패합니다.

401이 잔액 부족일 수도 있나요?

아니요. 잔액 부족은 크레딧을 언급하는 메시지와 함께 402로 표시됩니다. 401은 항상 신원 확인 문제입니다.

curl에서는 작동하지만 내 코드에서는 실패합니다. 왜 그런가요?

거의 항상 코드가 다른 환경 변수를 읽거나, export가 전달되지 않은 다른 셸/컨테이너에서 실행되기 때문입니다. 프로세스 내부에서 자격 증명을 마스킹해 출력하여 확인하세요.