• 목록

외부 API를 호출했는데 타임아웃이 발생하면 서버가 느리다는 결론부터 내리기 쉽습니다. 하지만 연결을 만들지 못한 경우와 응답 데이터를 기다리다 멈춘 경우는 확인할 지점이 다릅니다.

HTTP 클라이언트의 대기 단계를 나누어 이해하면 설정값과 오류 기록을 더 정확하게 읽을 수 있습니다.

AI 생성 삽화 · 실사풍 연출 이미지입니다. 실제 고객 현장이나 실제 작업 결과를 촬영한 사진이 아닙니다.

핵심 정리
타임아웃은 어떤 단계에서 얼마나 기다릴지를 정하는 제한입니다. 연결·읽기·쓰기·연결 풀 대기를 구분하고, 개별 제한과 전체 작업의 마감 시간을 별도로 생각해야 합니다.

1. 타임아웃 메시지에서 대기 단계를 찾습니다

HTTPX 공식 문서는 타임아웃을 connect, read, write, pool의 네 종류로 구분합니다. 연결을 만드는 대기, 데이터를 받는 대기, 데이터를 보내는 대기, 재사용할 연결을 풀에서 얻는 대기는 서로 다른 상황입니다.

예를 들어 연결 풀에서 기다리다가 제한에 걸렸다면 요청이 상대 서버까지 전달되었는지부터 확인해야 합니다. 반대로 연결을 이미 만든 뒤 응답을 기다리는 문제라면 연결 설정만 늘리는 것으로 해결되지 않을 수 있습니다.

처음 오류를 읽을 때는 타임아웃이라는 공통 단어보다 예외 종류와 발생 위치를 먼저 봅니다. 같은 화면에 표시되는 요청 실패라도 내부 원인이 같다는 보장은 없습니다.

서비스 로그에 모든 실패를 한 문구로 합쳐 버리면 이 구분이 사라지므로 개발 단계에서 원래 예외 정보를 확인할 수 있는 구조가 도움이 됩니다.

2. 읽기 제한과 전체 소요 시간을 구분합니다

HTTPX의 read timeout은 응답 전체를 받는 총시간이 아니라 데이터 조각을 받기까지 기다리는 시간을 기준으로 설명됩니다. Requests 문서 역시 timeout을 전체 다운로드 시간의 상한으로 해석하지 않도록 안내합니다.

따라서 어떤 라이브러리에서 timeout을 5초로 설정했다는 사실만으로 모든 요청이 시작 후 정확히 5초 안에 끝난다고 말할 수는 없습니다. 가상으로 응답 데이터가 조금씩 계속 들어오는 작업을 생각해 보겠습니다.

각 수신 사이의 대기는 짧아도 최종 파일을 다 받을 때까지는 더 오래 걸릴 수 있습니다. 이 예시의 숫자는 권장 설정이 아니라 시간의 기준을 구분하기 위한 설명입니다.

실제 동작은 사용하는 클라이언트와 전송 방식의 문서를 확인해야 하며, 다른 라이브러리의 옵션 이름이 비슷하다고 의미까지 같다고 가정하지 않습니다.

3. 사용자가 기다릴 전체 시간을 먼저 정합니다

상품 상세 화면을 여는 요청과 야간에 대량 파일을 내려받는 작업은 기다릴 수 있는 조건이 다릅니다. 개발자는 먼저 호출자가 언제까지 결과를 필요로 하는지 정하고 그 안에서 외부 호출과 후처리에 사용할 시간을 나누어 생각할 수 있습니다.

예를 들어 화면 응답 예산을 가상의 3초로 잡았다면 외부 API에만 3초를 모두 배정하고 나머지 처리 시간을 잊어서는 안 됩니다. 인증 확인이나 결과 변환, 다른 서비스 호출이 앞뒤에 있을 수 있기 때문입니다.

이처럼 작업 시작부터 끝까지의 마감 시간은 단계별 타임아웃과 별개로 설계해야 합니다. 어떤 계층이 마감 시간을 관리하는지와 남은 시간을 하위 호출에 어떻게 전달할지도 팀 안에서 정합니다.

모든 서비스에 같은 초 단위 값을 복사하는 방식보다 호출 목적과 사용자 경험을 함께 설명할 수 있어야 합니다.

4. 클라이언트의 포기가 서버의 취소는 아닙니다

클라이언트가 더 기다리지 않기로 했다는 사실만으로 상대 서버의 작업이 취소되었다고 단정할 수는 없습니다. 요청이 전달된 뒤 응답만 늦었을 가능성과 요청 자체가 전달되지 않았을 가능성을 구분해야 합니다.

가상 주문 API에서 클라이언트가 타임아웃을 받았다고 생각해 보겠습니다. 서버에는 주문이 이미 저장되어 있지만 응답을 받지 못한 상태일 수도 있으므로 즉시 같은 주문을 새로 만들면 중복 처리가 생길 수 있습니다.

이때는 해당 API가 제공하는 요청 식별자나 결과 조회 방식, 중복 처리 방지 규약을 확인해야 합니다. 타임아웃 예외 하나만으로 업무 결과를 성공 또는 미처리로 확정하지 않는 것이 핵심입니다.

취소 신호가 실제로 전파되는지 역시 사용하는 서버와 프로토콜, 애플리케이션 구현에 따라 확인할 문제입니다.

5. 재시도까지 포함한 시간표를 그립니다

한 번의 외부 호출에 2초를 기다리고 최대 세 번 시도하는 가상 정책이 있다고 가정해 보겠습니다. 시도 사이에 쉬는 시간과 각 단계의 부가 비용이 있다면 전체 작업은 2초보다 훨씬 길어질 수 있습니다.

그렇다고 이 숫자를 단순 곱셈한 값이 언제나 정확한 상한이 되는 것도 아닙니다. 호출마다 어떤 제한이 적용되는지와 전체 마감 시간이 있는지에 따라 실제 동작이 달라집니다.

설계 검토에서는 첫 시도 시작, 실패, 대기, 다음 시도, 최종 종료를 한 줄의 시간표로 적어 보는 방법이 좋습니다. 남은 시간이 짧은데도 새 시도를 시작할지, 업무상 재시도가 가능한 요청인지도 함께 검토합니다.

이 글의 목적은 특정 재시도 횟수를 권하는 것이 아니라 개별 요청의 설정이 사용자에게 보이는 대기 시간과 어떻게 연결되는지 확인하는 데 있습니다.

6. 로그에는 원인을 좁힐 정보를 남깁니다

타임아웃이 늘었을 때 설정값부터 높이기보다 어느 호출과 단계에서 발생하는지 살펴봅니다. 요청 식별자, 대상 서비스의 논리적 이름, 예외 종류, 경과 시간, 재시도 횟수처럼 문제를 연결할 정보를 남길 수 있습니다.

인증 토큰이나 개인정보가 포함된 전체 URL과 요청 본문을 그대로 기록하는 방식은 피하고 필요한 항목만 선택합니다. 가상으로 특정 외부 API의 읽기 타임아웃만 증가했다면 같은 시각의 응답 지연과 요청량을 비교해 볼 수 있습니다.

연결 풀 대기만 증가했다면 애플리케이션의 동시 호출과 연결 반환 상태도 확인 대상이 됩니다. 이런 관찰은 곧바로 원인을 확정한다는 뜻이 아닙니다.

어떤 가설을 먼저 검증할지 정하기 위한 자료이며, 지표와 로그가 같은 요청 구간을 측정하는지도 함께 확인해야 합니다.

7. 설정 검토를 질문 목록으로 정리합니다

실무에서 설정을 읽을 때는 이 값이 어느 단계의 제한인지, 기본값을 상속하는지, 호출별로 덮어쓰는지부터 확인합니다. 이어 전체 작업의 마감 시간이 어디에서 관리되는지, 타임아웃 후 결과를 어떻게 확인하는지, 재시도 가능한 업무인지 질문합니다.

학습용으로는 지연을 통제할 수 있는 테스트 서버에서 연결 이후 응답을 늦추는 경우와 데이터를 조금씩 보내는 경우를 비교해 볼 수 있습니다. 실제 외부 서비스에 불필요한 부하를 주는 실험은 필요하지 않습니다.

검토 결과에는 라이브러리 버전과 적용한 설정의 위치를 기록하면 이후 변경 시 비교하기 좋습니다. 타임아웃을 이해했다는 것은 적절해 보이는 숫자 하나를 고른 상태가 아닙니다.

어느 대기를 끝내고 그 이후 사용자와 업무 상태를 어떻게 처리할지 설명할 수 있는 상태입니다. 설정 변경 제안에는 기존 값과 새 값만 적기보다 예상되는 영향을 함께 적어 봅니다.

읽기 대기를 늘리면 어떤 요청의 성공 가능성을 기대하는지, 그동안 연결과 사용자 대기가 얼마나 더 유지될 수 있는지 질문합니다. 가설이 없는 변경은 문제가 줄어도 이유를 설명하기 어렵습니다.

관찰할 지표와 되돌릴 조건을 정해 두면 숫자 조정이 원인 분석을 대신하는 상황을 줄일 수 있습니다.

8. 자주 묻는 질문

Q1. timeout=5이면 요청 전체가 5초 안에 끝나나요?

라이브러리마다 의미가 다르므로 그렇게 단정할 수 없습니다. 읽기 대기 제한인지 전체 마감 시간인지 공식 문서에서 확인해야 합니다.

Q2. 타임아웃이 나면 값을 늘리는 것이 맞나요?

먼저 발생 단계와 호출 목적을 확인합니다. 값을 늘리면 대기만 길어질 수 있으므로 원인과 전체 응답 예산을 함께 검토해야 합니다.

Q3. 타임아웃이면 서버 작업은 실패한 것인가요?

클라이언트가 결과를 받지 못했다는 사실과 서버의 업무 결과는 다를 수 있습니다. 결과 조회나 요청 식별 방식으로 상태를 확인할 수 있게 설계합니다.

Q4. 모든 API에 같은 제한을 적용해도 되나요?

공통 기본값은 둘 수 있지만 작업 목적과 응답 특성이 다를 수 있습니다. 예외 설정에는 이유와 전체 시간 예산을 함께 남기는 편이 좋습니다.

참고 자료

• HTTPX 공식 문서: Timeouts
• Requests 공식 문서: Timeouts