Claude API 요청 타임아웃 및 “streaming is strongly recommended”

일반적으로 사용자와 모델 사이에는 SDK의 타임아웃, 중간 계층의 타임아웃, 긴 비스트리밍 호출에 대한 제공업체 자체 규칙이라는 세 가지 타임아웃이 있습니다. 가장 짧은 제한이 적용됩니다. SDK 제한만 늘린 뒤에도 문제가 계속되는 이유가 여기에 있습니다.

오류

two shapes

# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
 "message":"Streaming is strongly recommended for operations that may take
 longer than 10 minutes."}}

# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.

원인과 해결 방법 한눈에 보기

원인	해결 방법
긴 비스트리밍 생성	스트리밍하세요. 긴 완성 결과는 기다리는 것이 아니라 스트리밍되는 것이 전제입니다.
SDK 클라이언트 타임아웃이 생성 시간보다 짧음	늘리세요. 단, 중간 계층의 제한도 함께 늘리지 않으면 아무것도 바뀌지 않습니다.
프록시, 로드 밸런서 또는 요청을 제한하는 서버리스 함수	체인에서 가장 짧은 제한을 찾으세요. 바로 그 제한에 도달한 것입니다.
연결은 수락되었지만 응답이 없음	느린 응답이 아니라 멈춘 상태입니다. 첫 바이트까지의 시간은 별도로 제한하세요.

몇 분 이상 걸릴 수 있는 모든 작업은 스트리밍하세요

제한을 피하는 것 외에도 스트리밍은 연결 상태 신호를 제공합니다. 토큰이 도착한다는 것은 모델이 작업 중이라는 뜻이므로, 멈춤과 느린 진행을 구분할 수 있습니다. 단일 블로킹 호출에서는 타임아웃이 발생할 때까지 두 상황이 똑같아 보입니다.

SDK뿐 아니라 체인의 모든 타임아웃을 늘리세요

사람들은 거의 항상 클라이언트만 변경하고 끝냅니다. 리버스 프록시나 서버리스 플랫폼이 새 클라이언트 타임아웃보다 짧게 요청을 제한한다면 그 제한이 여전히 적용되므로 증상은 달라지지 않습니다.

client.py

from anthropic import Anthropic

# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": prompt}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

첫 바이트까지의 시간을 전체 지속 시간과 별도로 제한하세요

이는 서로 다른 해결책이 필요한 두 가지 다른 장애입니다. 짧은 첫 바이트 기한은 끊어진 연결을 빠르게 감지하고, 넉넉한 전체 기한은 실제로 오래 걸리는 생성을 완료하게 합니다. 하나의 통합 타임아웃으로는 두 가지를 모두 처리할 수 없습니다.

재시도를 추가하기 전에 안전하게 만드세요

여러분의 측면에서 타임아웃된 요청이 업스트림에서는 완료되었을 수 있습니다. 작업에 부작용이 있거나 호출당 요금이 부과된다면 재시도 루프를 추가하기 전에 여러분의 계층에 멱등성을 추가하세요.

Kunavo를 통해 호출하는 경우

Kunavo는 여러분이 직접 확인하지 않아도 되도록 자체 수치를 공개합니다. 업스트림 응답 헤더를 최대 240초 동안 기다리며, 비스트리밍 응답은 일반적으로 완료된 후에야 헤더를 보내므로 그보다 오래 걸리는 비스트리밍 호출은 게이트웨이를 통해 완료되지 않습니다 — 스트리밍하세요. 240초 제한은 헤더까지의 시간에만 적용되며 헤더가 도착하는 즉시 해제되므로 긴 스트림을 절대 잘라내지 않습니다. 게이트웨이의 다른 어떤 요소도 스트림 길이를 제한하지 않습니다. 스트림을 종료하는 것은 무응답입니다. 업스트림에서 300초 동안 바이트가 하나도 오지 않거나, 여러분과의 연결에서 600초 동안 바이트가 하나도 오지 않으면 종료됩니다. 동기식 이미지, 비디오 및 음악 경로는 렌더링이 완료되는 동안 최대 540초까지 연결을 유지하며, 이는 600초 창 안에 있습니다. 렌더링에는 실제로 수 분이 걸릴 수 있기 때문입니다. 헤더 전에 타임아웃된 요청은 채널 장애로 처리되어, 구성이 되어 있는 경우 모델의 다음 채널에서 재시도되며 비용은 0으로 기록됩니다.

자주 묻는 질문

타임아웃된 요청에도 요금이 청구되나요?

Kunavo에서는 아닙니다 — 실패한 요청은 비용 0으로 기록됩니다. 공급자와 직접 결제하는 경우에는 실제로 생성이 수행되었는지에 따라 달라집니다.

스트리밍은 왜 제한을 피하나요?

응답이 수 초 안에 시작되고 연결이 계속 사용 중이므로, 타임아웃을 발생시킬 만큼 긴 무응답 구간이 없습니다.

클라이언트 타임아웃은 얼마로 설정해야 하나요?

현실적으로 예상되는 최악의 생성 시간보다 길게 설정하고, 별도로 짧은 첫 바이트 기한을 두세요. 긴 통합 타임아웃 하나만 사용하면 모든 멈춤이 수 분간의 지연으로 바뀝니다.

Claude API 요청 타임아웃 및 “streaming is strongly recommended” — 10분 규칙

오류