파이썬 urllib 403 error code 1010 원인과 해결

먼저 결론

겪은 일: 파이썬 urllib 으로 API 나 페이지를 부르면 HTTP Error 403 과 본문 error code: 1010 이 옵니다.

원인: 키가 틀린 것이 아닙니다. Cloudflare 뒤에 있는 주소가 파이썬 기본 요청을 로봇으로 보고 막습니다.

이렇게 풀었다: 요청에 브라우저 User-Agent 와 Accept 헤더를 붙입니다. 403 을 보면 본문의 오류 코드부터 읽습니다.

같은 주소, 헤더 하나 차이

서버의 배치 작업에서 메일 발송 API 를 파이썬 urllib 으로 불렀더니 HTTP 403, error code 1010 이 돌아왔습니다. 다른 날에는 이미지 생성 API 에서 똑같은 일이 있었습니다. 파이썬 기본 요청은 403 1010 이었고, 같은 키로 curl 을 부르니 200 이 나왔습니다.

그때 이 차이를 놓치고 멀쩡한 키를 "죽었으니 새로 받아야 한다"고 판단했습니다. 키는 아무 문제가 없었습니다.

이 글을 쓰면서 Cloudflare 뒤에 있는 제 사이트 하나에 다시 확인했습니다. 같은 주소에 헤더만 바꿔 한 번씩 요청한 결과입니다.

요청 상태 코드 응답 본문 server 헤더
urllib 기본(헤더 없음) 403 error code: 1010 cloudflare
브라우저 User-Agent 와 Accept 를 붙임 200 정상 페이지 cloudflare

헤더를 아무것도 주지 않으면 urllib 은 Python-urllib/3.9 같은 User-Agent 를 스스로 붙여 보냅니다. 이 값만 보고도 사람이 아닌 프로그램이라는 것이 드러납니다.

1010 은 인증 실패가 아니라 차단이다

403 이라는 숫자만 보면 "권한이 없다"로 읽기 쉽습니다. 그런데 본문을 열어 보면 서로 전혀 다른 일이 섞여 있습니다. 상태 코드보다 본문의 오류 코드를 먼저 읽어야 하는 이유입니다.

본 것 뜻 할 일
403, 본문 error code: 1010, server 헤더 cloudflare 요청을 보낸 프로그램 모양 때문에 앞단에서 차단 헤더를 붙인다. 키는 그대로
401, 본문에 invalid token 같은 문구 인증 실패 키 값과 키를 읽는 경로를 확인

1010 은 요청이 API 서버까지 가지도 못하고 Cloudflare 에서 멈췄다는 신호로 읽으면 됩니다. Cloudflare 가 정확히 어떤 값을 보고 막는지는 확인하지 못했습니다. 다만 위 재현처럼 User-Agent 하나로 결과가 갈렸습니다.

맨 curl 도 막힐 수 있습니다. 메일 발송 API 에서는 헤더 없는 curl 도 403 1010 이었습니다. 반대로 이미지 API 에서는 curl 이 200 이었습니다. 그러니 "curl 은 되는데"가 늘 통하는 확인법은 아닙니다.

고치는 코드

요청 객체를 만들 때 헤더를 넣습니다. JSON 을 주고받는 API 라면 Accept: application/json 도 함께 줍니다.

import json, urllib.request, urllib.error

UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
      "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0 Safari/537.36")

req = urllib.request.Request(
    "https://api.example.com/v1/send",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "User-Agent": UA,
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer " + api_key,
    },
    method="POST",
)
try:
    with urllib.request.urlopen(req, timeout=20) as r:
        print(r.status)
except urllib.error.HTTPError as e:
    body = e.read(400).decode("utf-8", "replace")
    print(e.code, e.headers.get("server"), body)

핵심은 except 에서 상태 코드만 찍지 말고 본문 앞부분과 server 헤더까지 찍는 것입니다. 이것만 있었어도 키를 의심하는 일은 없었습니다. 오류를 삼켜서 원인이 사라지는 다른 경우는 파이썬이 조용히 실패하는 경우에 따로 모았습니다.

함께 헷갈린 401: 환경변수 파일의 따옴표

같은 메일 발송 작업에서는 401 이 난 적도 있었습니다. 이것도 키 문제로 오진할 뻔했습니다. 원인은 환경변수 파일이었습니다.

보내는 사람 값을 MAIL_FROM=이름 <[email protected]> 처럼 공백과 꺾쇠가 든 채 따옴표 없이 적어 두었습니다. 셸에서 이 파일을 source 하면 그 줄에서 통째로 깨져 뒤에 있던 API 키까지 읽히지 않았습니다. 키가 비어 있으니 401 이 난 것입니다.

# 깨지는 줄
MAIL_FROM=이름 <[email protected]>

# 고친 줄
MAIL_FROM="이름 <[email protected]>"

정리하면 403 1010 은 헤더, 401 은 키를 읽는 길부터 봅니다. 서버에서 curl 로 결과를 확인할 때 생기는 다른 착각은 curl 로 라이브를 확인할 때 하는 실수에 적었습니다.

확인한 환경 값
재현한 PC Windows 10 Pro, Python 3.9.13 표준 라이브러리 urllib
재현 날짜 2026년 10월 5일 (헤더 없이 1회, 붙여서 1회)
처음 겪은 날 2026년 9월 2일(메일 API), 9월 15일(이미지 API)

이 글의 내용은 2026년 10월 12일에 마지막으로 확인했습니다. 틀린 곳을 발견하시면 연락처로 알려 주세요.