API Timeout 원인 진단 및 안전한 재시도 판단 가이드

API Timeout은 요청 경로의 어느 한 계층이 기다리기를 중단했다는 뜻입니다. 클라이언트가 연결하지 못했거나, 프록시가 유휴 stream을 닫았거나, 애플리케이션의 전체 deadline이 만료되었거나, gateway가 upstream 모델의 응답을 제시간에 받지 못했을 수 있습니다. 이 메시지만으로 모델 장애라고 판단할 수는 없습니다.

재시도 전에 예외 종류, 가능한 HTTP status와 body, 경과 시간, request ID, 수신한 chunk의 유무를 기록하세요. 증거로 확인된 계층의 제한만 변경해야 합니다. 모든 timeout을 동시에 늘리면 원인이 가려지고 결과를 알 수 없는 작업이 중복될 수 있습니다.

BetterToken을 사용한 요청이라면 retry 전에 Dashboard를 열어 시간, 모델, status, Token 사용량을 대조하세요. API에 도달한 요청과 gateway 이전의 실패를 즉시 구분할 수 있습니다.

하나의 timeout에 여러 원인이 있는 이유

애플리케이션 / SDK
  → DNS와 TCP/TLS
  → 사내 proxy 또는 reverse proxy
  → API gateway
  → upstream 모델
  → 클라이언트로 돌아오는 streaming 응답

Connect timeout은 DNS, TCP, TLS 연결 설정에 적용됩니다. Read 또는 stream-idle timeout은 클라이언트 제한 안에 다음 chunk가 오지 않은 상태입니다. Pool timeout은 사용 가능한 클라이언트 연결을 기다리는 제한입니다. 전체 deadline은 전체 비즈니스 작업을 제한하고, upstream timeout은 gateway나 provider가 소유한 별도 제한입니다. 하나를 늘려도 다른 제한은 연장되지 않습니다.

중단된 계층을 찾는 방법

관측 신호	가능성이 높은 계층	다음 확인
httpx.ConnectTimeout, HTTP 응답 없음	DNS, TCP 또는 TLS	같은 runtime에서 재현하고 DNS, CA, proxy, firewall 비교
chunk 전이나 사이에 httpx.ReadTimeout	client read/idle 또는 중간 proxy	first byte와 chunk 간격을 측정하고 proxy idle 제한 확인
HTTP status와 error body가 있음	gateway 또는 upstream	status, body, request ID를 저장하고 provider error contract 적용
httpx.PoolTimeout	client connection pool	concurrency와 pool 점유율을 측정하고 포화가 확인된 경우에만 제한 변경
매번 같은 총 시간에 취소	application, job runner 또는 reverse proxy	deadline 소유자를 찾고 하위 timer와 비교

순서는 신호 보존, 동일한 host 또는 container에서 재현, 중간 proxy 확인, gateway와 upstream 확인입니다. 모델, prompt, network, endpoint, proxy는 고정하고 테스트마다 한 변수만 바꾸세요.

HTTPX는 connect, read, write, pool timeout을 각각 정의합니다. 모든 환경에 맞는 하나의 초 단위 값은 없습니다. 실제 값은 측정한 request phase, chunk 사이의 예상 공백, 전체 deadline을 기준으로 결정해야 합니다.

timeout, 출력량 또는 retry를 바꾸는 조건

• DNS/TCP/TLS 설정이 실제로 늦다는 증거가 있을 때만 connect timeout을 변경합니다.
• 연결은 되었지만 chunk 사이에서 확인된 중간 제한이 만료될 때만 read 또는 idle timeout을 변경합니다.
• 하위 계층이 정상이고 비즈니스 작업이 더 오래 걸려도 되는 경우에만 전체 deadline을 늘립니다.
• 제어한 긴 테스트만 실패하면 출력을 줄이거나 나눕니다. 측정 없이 원인으로 단정하지 마세요.
• 429와 context overflow는 별도 신호입니다. connect timeout과 혼합하지 않습니다.

알 수 없는 작업을 중복하지 않는 안전한 retry

요청을 보낸 뒤 발생한 timeout은 먼저 결과 불명으로 취급합니다. 로컬 task ID는 로그를 연결하는 데 도움이 되지만 서버의 두 번째 작업을 막지는 못합니다. 서버가 문서화된 idempotency 또는 status lookup을 제공하고 외부 증거가 첫 요청이 수락되지 않았음을 보여줄 때만 자동 재시도하세요.

최소 체크리스트:

1. request ID, status/body, timestamp, 수신한 chunk를 저장합니다.
2. 비멱등 작업을 반복하기 전에 실제 결과를 확인합니다.
3. 일부를 받은 stream을 자동으로 다시 보내지 않습니다. 두 번째 generation과 추가 사용량이 생길 수 있습니다.
4. 시도 횟수와 전체 deadline을 모두 제한하고 SDK, proxy, application retry를 합산합니다.
5. response 객체 생성 시점뿐 아니라 SSE iteration 도중의 오류도 포착합니다.

두 가지 테스트로 복구를 확인

1. 짧은 대조 요청: 작은 응답을 요청하고 status, first byte 시간, 총 소요 시간, request ID, stream 완료 여부를 기록합니다. 실패하면 먼저 network, authentication, endpoint를 확인합니다.
2. 제어된 긴 요청: 짧은 테스트가 성공한 뒤 예상 출력만 늘리거나 원래 workload를 복원합니다. 모델, endpoint, network, proxy는 바꾸지 않습니다. 이 테스트만 실패하면 read/idle timeout, 전체 deadline, 중간 제한을 비교합니다.

짧은 테스트와 원래 시나리오의 한 번의 재실행이 예상 결과로 끝나고 설명되지 않는 중복이 없을 때 복구가 확인됩니다. 요청이 BetterToken에 도달했다면 Dashboard에서 시간, 모델, status, Token 사용량을 대조하고 endpoint contract를 확인하세요.

출처

• HTTPX timeout 종류
• OpenAI API error handling
• Claude API errors와 request ID