파이썬 API 호출에서 OAuth Bearer 인증을 사용하는 경우라면 401은 인증 정보의 유효성을, 403은 필요한 권한의 부족 여부를 먼저 살펴볼 수 있지만, 실제 판단은 서비스의 오류 정의와 응답을 확인해야 합니다. 다만 서비스마다 상태 코드와 오류 본문을 다르게 구현할 수 있으므로, 응답 헤더와 본문을 함께 보면서 실제로 전송된 Authorization 헤더를 좁혀 가야 합니다. 먼저 볼 부분은 토큰을 만들었다는 사실이 아니라 Python 요청 객체에 어떤 값이 들어갔는지입니다.
401과 403을 먼저 나누는 기준
OAuth Bearer 표준에서는 만료·철회·변형·무효 토큰을 invalid_token과 함께 401로 처리하는 경우가 일반적이고, 유효한 토큰이라도 필요한 scope가 부족하면 insufficient_scope와 함께 403으로 처리하는 경우가 일반적입니다. 이 기준은 진단 방향을 정해 주지만, 서비스가 표준을 그대로 따르는지는 확인해야 합니다.
따라서 다음처럼 생각하면 됩니다.
- 401: 헤더가 빠졌는지,
Bearer접두사와 토큰 사이 공백이 올바른지, 토큰이 만료되거나 무효가 되었는지 확인합니다. - 403: 인증 자체는 통과했는지 확인한 뒤 엔드포인트, scope, 역할 또는 리소스 접근 권한을 API 제공자의 문서와 계정 설정에서 확인합니다.
응답의 WWW-Authenticate 헤더에 error나 scope가 있으면 원인 분류에 도움이 됩니다. 오류 본문이 JSON이라는 보장은 없으므로, 기록 코드는 본문 형식을 단정하지 않고 상태 코드·응답 헤더·본문에서 민감정보를 제거한 필요한 부분을 각각 남기는 편이 안전합니다.
실제 Authorization 헤더를 만들었는지 확인하기
Bearer 토큰은 Authorization 헤더에 Bearer와 하나 이상의 공백, 그리고 토큰을 이어 붙이는 형식입니다. 환경변수 로드 문제와 인증 형식 문제를 한꺼번에 추측하지 말고, 비밀값 자체는 출력하지 않은 채 헤더의 존재와 접두사만 점검합니다.
import os
import requests
token = os.environ.get("API_TOKEN", "").strip()
headers = {
"Authorization": f"Bearer {token}",
"Accept": "application/json",
}
if not token:
raise RuntimeError("API_TOKEN이 비어 있습니다.")
response = requests.get(
"https://api.example.com/items",
headers=headers,
timeout=float(os.environ["API_TIMEOUT_SECONDS"]),
)
print("status:", response.status_code)
print("authorization_present:", "Authorization" in response.request.headers)
print("bearer_scheme:", response.request.headers.get("Authorization", "").startswith("Bearer "))
예제 URL과 masked-token은 가상의 값이며, 실행할 때는 서비스의 실제 엔드포인트와 환경변수 API_TIMEOUT_SECONDS의 적절한 초 단위 제한값을 설정합니다. 여기서 확인할 것은 토큰을 출력하는 일이 아닙니다. response.request.headers에서 최종 요청의 헤더 존재 여부와 접두사를 비밀값 없이 확인하는 일입니다. headers 딕셔너리는 설정값이므로 실제 전송 요청과 구분해야 합니다. strip()은 복사 과정에서 토큰 앞뒤에 들어간 공백을 제거하지만, 토큰 내부를 임의로 바꾸지는 않습니다.
Requests의 인증값 우선순위를 의심하기
Requests에서는 headers에 Authorization을 넣어도 다른 인증 설정이 그 값을 덮을 수 있습니다. 공식 문서에 따르면 auth 인자가 가장 높은 우선순위를 가지며, 그다음이 URL 호스트에 대한 netrc 자격증명이고, 직접 설정한 headers가 그 뒤를 따릅니다. netrc 사용은 trust_env=False로 끌 수 있습니다.
import os
import requests
session = requests.Session()
session.trust_env = False
response = session.get(
"https://api.example.com/items",
headers={"Authorization": "Bearer masked-token"},
timeout=float(os.environ["API_TIMEOUT_SECONDS"]),
)
이 설정은 모든 환경에서 무조건 사용하라는 뜻이 아닙니다. Postman에서는 되는데 특정 실행 계정의 Python만 실패한다면 auth=, netrc, Session 설정과 프록시·환경 설정을 차례로 비교하라는 의미입니다. 자격증명 파일과 토큰을 로그에 남기지 않는 것도 함께 지켜야 합니다.
urllib를 사용할 때도 같은 헤더를 확인하기
urllib.request.Request는 생성자의 headers 인자나 add_header()로 요청 헤더를 설정할 수 있습니다. 라이브러리를 바꾸면 인증 원인이 자동으로 사라지는 것은 아니므로, Requests와 마찬가지로 실제 요청에 들어갈 헤더 값과 최종 URL을 확인해야 합니다.
리디렉션 뒤에 헤더가 사라졌는지 확인하기
요청 URL이 다른 호스트로 이동하는 리디렉션을 거치면 Requests는 보안을 위해 Authorization 헤더를 제거할 수 있습니다. 처음 URL에서는 정상이어도 최종 URL의 호스트가 달라졌다면, 최종 요청이 인증 없이 도착해 401을 만들 수 있습니다.
response = requests.get(
"https://api.example.com/items",
headers={"Authorization": "Bearer masked-token"},
allow_redirects=False,
timeout=float(os.environ["API_TIMEOUT_SECONDS"]),
)
print("status:", response.status_code)
print("location:", response.headers.get("Location"))
이 코드는 앞서 가져온 os와 requests를 사용하며, 같은 환경변수의 시간 제한값을 적용합니다. 먼저 리디렉션을 자동으로 따라가지 않고 Location을 확인해 호스트가 바뀌는지 봅니다. 새 호스트에 토큰을 그대로 전달하는 코드를 급하게 추가하기보다, API의 공식 기본 URL과 인증 방식에 맞는 최종 엔드포인트를 사용해야 합니다. 호스트가 바뀌는 요청에 자격증명을 무조건 재전송하면 보안 문제가 생길 수 있습니다.
응답 단서로 다음 조치를 선택하기
진단 로그에는 다음 항목을 분리해 남기면 원인 추적이 쉬워집니다.
- HTTP 상태 코드
WWW-Authenticate같은 응답 헤더- 응답 본문 전체가 아니라 민감정보를 제거한 필요한 부분
- 최종 요청 URL과 리디렉션 여부
401인데 invalid_token 단서가 있으면 토큰의 만료·철회·변형과 Bearer 형식을 점검합니다. 403인데 insufficient_scope 또는 scope 정보가 있으면 헤더를 계속 고치기보다 해당 엔드포인트에 필요한 권한을 확인합니다. 아무 단서도 없으면 서비스 문서의 오류 정의와 실제 요청 URL, HTTP method, 계정 역할을 함께 비교합니다.
점검 순서 요약
저라면 다음 순서로 좁혀 갑니다.
headers에Authorization이 실제로 만들어졌는지 비밀값 없이 확인합니다.Bearer접두사와 토큰 사이 공백, 빈 토큰, 앞뒤 공백을 확인합니다.- Requests의
auth,netrc,Session.trust_env설정이 값을 덮는지 봅니다. - 리디렉션을 잠시 끄고 최종 호스트와
Location을 확인합니다. - 401이면 토큰 유효성 단서, 403이면 scope·역할·엔드포인트 권한 단서를 확인합니다.
응답 단서가 부족하면 제공자의 오류 정의와 요청 대상, 계정 권한을 함께 확인해야 합니다. 반대로 계속 401이라면 API 상품이나 요금제를 추측하기보다 실제 요청 헤더를 만드는 코드와 리디렉션부터 다시 확인하는 편이 빠릅니다.