Python TimeoutError: 요청 시간 초과 오류 해결 가이드

Python TimeoutError란?

`TimeoutError`는 네트워크 요청, 파일 입출력, 쓰레딩 등에서 특정 작업이 지정된 시간 안에 완료되지 못했을 때 발생하는 예외입니다. 이 오류는 주로 외부 API 호출, 소켓 통신, 데이터베이스 연결, 대기 시간 설정 등에서 자주 마주치며, 네트워크 환경에 민감한 애플리케이션에서 중요하게 다뤄야 합니다.

1. TimeoutError가 발생하는 주요 상황

인터넷 연결이 불안정하거나 서버 응답 지연
외부 API 요청에 timeout 옵션이 너무 짧게 설정됨
socket, threading 모듈 등에서 작업이 제한 시간 초과
서버 또는 리소스가 과부하 상태

2. TimeoutError 예시 코드


import requests

try:
    response = requests.get("https://httpbin.org/delay/5", timeout=2)
except requests.exceptions.Timeout:
    print("요청이 시간 초과되었습니다.")


requests.exceptions.Timeout: HTTPSConnectionPool(host='httpbin.org', port=443): Read timed out. (read timeout=2)

3. TimeoutError 해결 방법

3-1. timeout 값 늘리기

외부 요청의 timeout 시간을 늘려 서버 응답을 기다릴 수 있도록 합니다.


response = requests.get("https://httpbin.org/delay/5", timeout=10)

3-2. 예외 처리 추가

`try-except` 구문으로 `TimeoutError` 또는 관련 예외를 처리해 사용자에게 안내 메시지를 제공하거나 재시도를 유도할 수 있습니다.


import requests

try:
    response = requests.get("https://example.com", timeout=3)
    print(response.text)
except requests.exceptions.Timeout:
    print("시간 초과 오류 발생, 다시 시도하세요.")

3-3. 재시도 로직 추가 (retry)

`requests` 라이브러리에서는 `urllib3.util.retry`를 활용해 자동 재시도 로직을 구성할 수 있습니다.


from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry
import requests

session = requests.Session()
retry = Retry(connect=3, backoff_factor=0.5)
adapter = HTTPAdapter(max_retries=retry)
session.mount("http://", adapter)
session.mount("https://", adapter)

try:
    response = session.get("https://example.com", timeout=5)
    print(response.status_code)
except requests.exceptions.Timeout:
    print("요청이 재시도 후에도 시간 초과되었습니다.")

3-4. socket 통신에서의 timeout 설정


import socket

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.settimeout(3)  # 3초 이내 응답 없으면 TimeoutError 발생

try:
    sock.connect(("example.com", 80))
except socket.timeout:
    print("소켓 연결 시간 초과")

3-5. 스레드, 비동기 작업에 timeout 적용

`concurrent.futures`의 `ThreadPoolExecutor`, `asyncio.wait_for` 등을 사용할 때에도 timeout 설정을 해야 합니다.


import asyncio

async def long_task():
    await asyncio.sleep(5)
    return "완료"

try:
    result = asyncio.run(asyncio.wait_for(long_task(), timeout=3))
except asyncio.TimeoutError:
    print("비동기 작업 시간 초과")

4. 상황별 대처 요약

상황	대응 방법
requests 외부 API	timeout 설정, 재시도 처리
소켓 통신	settimeout 사용
비동기 처리	asyncio.wait_for()로 제한

5. 요약 및 결론

`TimeoutError`는 외부 요청이나 작업이 제한 시간 내에 완료되지 않을 때 발생합니다.
timeout 값을 상황에 맞게 조정하고, 예외 처리를 반드시 추가해야 합니다.
네트워크 환경이 불안정한 경우 재시도 로직을 구성하면 안정성이 향상됩니다.
동기/비동기/소켓/스레드 환경 각각에 맞는 timeout 설정이 필요합니다.

이 가이드를 통해 Python의 `TimeoutError` 문제를 정확하게 진단하고, 안정적인 네트워크 및 시스템 코드를 구현할 수 있습니다.

luckyvibe 님의 블로그