401 Unauthorized

401 Unauthorized는 요청한 자원에 유효한 인증 정보가 없어 요청을 적용하지 않았음을 나타내는 HTTP 상태 코드입니다. 서버는 요구하는 인증 방식을 알리는 응답 헤더를 함께 보냅니다. 인증 정보 누락·만료·불일치 등을 확인할 출발점이며, 코드 하나만으로 어떤 자격 증명이 왜 거부됐는지까지 확정할 수는 없습니다.

인증을 요구하는 응답

HTTP 의미 명세의 401 정의는 대상 자원에 유효한 인증 자격 증명이 없는 경우를 설명합니다. 401을 생성하는 서버는 WWW-Authenticate 헤더에 해당 자원에 적용할 인증 요구를 적어 보내야 합니다. 클라이언트는 이 정보를 읽어 서버가 어떤 인증 방식을 기대하는지 판단합니다. 헤더의 형식과 인증 방식은 서비스의 계약에 따라 달라지므로 비밀번호 입력 화면이 반드시 나타나는 응답은 아닙니다.

API 요청에서 인증 헤더가 빠졌거나, 서버가 받아들이지 않는 값을 보냈다면 같은 상태 코드를 받을 수 있습니다. 하지만 토큰이 없다는 상황과 만료된 토큰을 보냈다는 상황은 복구 방법이 다릅니다. 응답 본문의 오류 설명과 서비스 문서를 함께 읽고, 요청이 실제로 도달한 주소와 계정을 확인합니다. 비밀값을 로그에 그대로 남기는 대신 인증 방식과 헤더 유무, 발급 대상 등 원인을 좁히는 정보를 기록합니다.

403과 프록시 인증의 구분

MDN의 401 설명은 403 응답과 비교해 인증 문제를 구분합니다. 401은 유효한 인증 정보를 제시하면 다시 요청할 여지가 있는 상황을 나타내며, 403은 서버가 요청을 이해했지만 처리를 거부하는 의미입니다. 403을 받았다고 인증이 반드시 성공했다고 역으로 확정하지는 않습니다. 서비스가 상세 원인을 숨기거나 자체 규칙을 적용할 수 있으므로 실제 접근 권한과 응답 설명을 대조합니다.

프록시가 요구하는 인증에는 407과 Proxy-Authenticate가 사용됩니다. 목적 서버의 계정과 중간 프록시의 계정은 인증 대상이 다릅니다. 사내 네트워크에서만 요청이 실패한다면 최종 API 외에 중간 서버가 응답했는지도 살핍니다. 상태 코드를 읽을 때 응답을 만든 주체를 함께 구분하면, 목적 서버의 토큰을 반복 교체하면서 실제 프록시 설정 문제를 놓치는 일을 줄일 수 있습니다.

실패 원인과 재시도의 조건

브라우저에서 로그인한 상태와 자동화 프로그램의 인증 상태도 분리됩니다. 브라우저가 보관한 쿠키를 SDK가 자동으로 공유한다고 기대하면 같은 이용자가 실행한 요청인데도 결과가 달라질 수 있습니다. 인증 정보가 어떤 클라이언트와 환경에 저장돼 있는지 확인하고, 서비스가 안내한 API용 인증 경로를 사용합니다. 운영 계정으로 접근한 결과와 테스트 계정으로 접근한 결과를 비교할 때도 계정의 차이를 기록합니다. 한 계정에서 요청이 성공했다고 다른 계정의 인증 설정까지 정상인 것은 아닙니다.

SDK나 CLI는 서버 응답을 자체 예외 메시지로 감쌀 수 있습니다. ‘인증 실패’라는 문구만 남았을 때는 원래 HTTP 상태와 응답 헤더, 오류 본문이 무엇이었는지 확인합니다. 요청에 토큰을 넣는 코드가 있어도 실행 환경에서 값을 읽지 못했거나 다른 주소로 요청했다면 기대한 자격 증명이 전송되지 않았을 수 있습니다. 정상 동작한 요청과 실패한 요청에서 주소·메서드·계정·인증 정보의 전달 경로를 비교합니다.

인증 정보를 갱신한 뒤 재시도하는 동작은 서비스가 지원하는 절차와 횟수 제한에 맞춰 수행합니다. 같은 잘못된 값을 무한히 다시 보내면 접근 상태가 바뀌지 않은 채 요청만 늘어납니다. AI 에이전트가 도구를 호출하는 과정에서도 인증 정보 준비와 실제 작업 수행은 단계가 다릅니다. 인증 오류를 고친 뒤에는 필요한 데이터나 작업 결과를 다시 확인하며, 다른 엔드포인트까지 같은 권한을 얻었다고 넓혀 해석하지 않습니다.