Retrofit2 Connection/Timeout 에러 트러블슈팅

초기 설정 문제: Connection/Timeout 에러

Retrofit을 사용하여 API 요청을 보냈는데, Connection Timeout이나 Socket Timeout 에러가 발생하는 경우가 있다.

필자도 개발하면서 종종 겪는 에러인데 이건 주로 서버 응답이 느리거나, 네트워크 상태가 불안정하거나, 또는 설정 자체가 잘못된 경우에 발생한다.

그래서 Connection Timeout이나 Socket Timeout 에러가 발생했을 때 어떻게 대응하는게 좋을지 정리해봤다.

 

 

우선 타임아웃의 종류와 발생 원인을 정리해보면 다음과 같다.

API 호출 시 발생하는 타임아웃은 크게 세 가지로 나눌 수 있으며, 각각 다른 시점에서 문제가 발생한다.

종류	발생 시점	원인
connectTimeout	서버와의 연결을 시도할 때	서버 주소(IP)에 도달할 수 없거나, 서버가 연결 요청에 응답하지 않을 때
readTimeout	연결된 후 데이터를 읽어 올 때	서버가 연결은 수락했지만, 응답 본문(Body)을 보내는 속도가 너무 느리거나 멈췄을 때
writeTimeout	연결된 후 데이터를 보낼 때	클라이언트가 서버로 요청 본문(Body)을 보내는 속도가 너무 느릴 때 (주로 큰 파일 업로드 시)

 

문제: 타임아웃 시간이 너무 짧다..

나는 대부분의 경우 readTimeout을 경험했는데 서버 측에서 복잡한 연산 때문에 응답을 늦게 보내거나 네트워크 상태가 일시적으로 불안정해졌을 때 발생한다.

 

.

해결책: OkHttpClient를 통한 명시적인 타임아웃 및 로깅 설정

기본 타임아웃(Timeout) 설정이 10초 내외로 짧게 설정되어 있거나, 네트워크 상태를 디버깅할 수 있는 로깅 인터셉터가 없는 경우 디버깅이 어렵다.

Retrofit은 OkHttpClient 위에서 동작하므로 타임아웃 설정과 로깅은 OkHttpClient에 명시적으로 적용해야 한다.

 

1. 안정적인 사용자 경험을 위해 기본 설정(보통 10초)보다 충분히 길게 타임아웃을 설정합니다.

예를 들어, 30초 정도로 설정해서 서버 연산이나 네트워크 지연에 대비할 수 있다.

 

2. HTTP 로깅 인터셉터를 활용하는 것도 좋은 방법이다.

타임아웃 에러가 발생하면 요청이 서버까지 도달했는지, 어떤 헤더를 보냈는지 등을 확인하는 것이 중요하다. HttpLoggingInterceptor를 사용하여 요청과 응답의 모든 상세 내용을 콘솔에 출력하면 에러 발생 직전의 통신 상태를 파악할 수 있어 디버깅에 필수적이다.

 

 

🛠️ 핵심 코드: OkHttpClient 설정

import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import java.util.concurrent.TimeUnit

// 1. HTTP 로깅 인터셉터 생성 (디버깅 시 유용)
val loggingInterceptor = HttpLoggingInterceptor().apply {
    // 실제 운영 환경에서는 NONE 또는 BASIC으로 설정하는 것이 좋습니다.
    level = HttpLoggingInterceptor.Level.BODY 
}

// 2. OkHttpClient 설정
val okHttpClient = OkHttpClient.Builder()
    // 💡 연결, 읽기, 쓰기 타임아웃을 넉넉하게 설정 (예: 30초)
    .connectTimeout(30, TimeUnit.SECONDS) 
    .readTimeout(30, TimeUnit.SECONDS)
    .writeTimeout(30, TimeUnit.SECONDS)
    .addInterceptor(loggingInterceptor)
    .build()

// 3. Retrofit 인스턴스 생성 시 OkHttpClient 연결
val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/") // 베이스 URL
    .client(okHttpClient) // ✨ 설정한 OkHttpClient 사용
    .addConverterFactory(GsonConverterFactory.create())
    .build()

// ... Service 인터페이스 생성

 

 

⏳ 팁: Logcat 확인

타임아웃 에러가 발생하면, Logcat에서 OkHttp 태그를 검색해보자.

• 만약 요청(Request) 로그가 보이고, 응답(Response) 로그가 보이지 않으면서 에러가 났다면, 대부분 readTimeout이 문제일 가능성이 높다. 서버가 응답을 보내는 데 시간이 너무 오래 걸린 것이다.
• 만약 요청 로그 자체가 보이지 않거나, 네트워크 관련 예외(java.net.ConnectException 등)와 함께 에러가 난다면, connectTimeout 문제일 가능성이 높다. 네트워크 연결 자체에 문제가 있거나 Base URL 설정이 잘못되었을 수 있으니 꼭 확인해보자.