Error 401 Unauthorized

401 Unauthorized 오류의 의미

401 Unauthorized는 요청이 API 엔드포인트에 도달했지만, 그 엔드포인트가 요청을 인증하지 못했음을 뜻합니다.

AI API 중계 서비스에서는 보통 키, 토큰, 헤더 형식, 프로바이더 프로필 중 하나가 요청을 받은 Base URL과 맞지 않습니다.

주요 원인

1. API 키가 없거나, 비어 있거나, 앞뒤 공백이 있거나, 비활성화·만료되었거나, 다른 서비스 계정에 속합니다.
2. OpenAI 호환 API에서 Bearer 접두사가 없거나, Anthropic 호환 API에 잘못된 헤더를 쓰는 등 Authorization 헤더 형식이 틀립니다.
3. API 키를 발급한 서비스와 다른 서비스를 Base URL에 넣었습니다. 예를 들어 Anthropic 키를 OpenAI 호환 중계 프로필에서 사용합니다.
4. Claude Code, Codex, Cursor, 셸 환경 변수, config.toml 중 하나가 방금 고친 새 키가 아니라 이전 키를 읽습니다.
5. 중계 서비스 계정이 비활성, 미활성화, 선택한 모델을 쓸 수 없거나, 다른 프로젝트·조직·워크스페이스 설정이 필요합니다.

해결 방법

1. 도구가 쓰는 유효 환경 변수와 설정 파일을 표시하거나 확인합니다. 특히 OPENAI_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, 서비스 고유 키를 확인하세요.
2. Base URL과 API 키가 같은 프로바이더 프로필인지 확인합니다. 서비스가 그 형식을 명시하지 않는 한 OpenAI 공식, Anthropic 공식, 제3자 중계 키를 섞지 마세요.
3. 요청 헤더 형식을 확인합니다. OpenAI 호환 엔드포인트는 보통 Authorization: Bearer YOUR_KEY를 쓰고, Anthropic 호환 엔드포인트는 서비스 고유 인증 헤더를 쓸 수 있습니다.
4. 서비스 대시보드에서 새 키를 만들고, Claude Code, Codex, Cursor, CC Switch의 복잡한 프로필을 바꾸기 전에 최소 요청을 한 번 시험합니다.
5. 같은 키가 curl에서는 되고 CLI에서 실패하면 터미널이나 앱을 다시 시작하고, 다른 설정 파일이 기대한 키를 덮어쓰지 않는지 확인합니다.

AI API 중계 서비스 이용 시 확인 사항

실패한 도구와 같은 Base URL, API 키, 모델 이름으로 시험하세요. 다른 키나 엔드포인트에서 요청이 성공해도 문제의 프로필이 유효하다고 증명되지 않습니다.

새 키가 curl에서는 되고 CLI에서 실패하면, CLI가 이전 환경 변수, 이전 프로필, 다른 설정 파일을 읽고 있을 수 있습니다.

연결 전에 확인할 항목은 Quickstart를 보세요.

서비스를 바꿀 시점

현재 키가 비활성화되었거나, 서비스가 필요한 인증 방식을 지원하지 않거나, 계정에서 대상 모델을 쓸 수 없다고 확인된 뒤에만 서비스를 바꾸세요. 401 오류의 대부분은 로컬 설정 문제입니다.