중단 이유 처리

Messages API에 요청을 보낼 때, Claude의 응답에는 모델이 응답 생성을 중단한 이유를 나타내는 stop_reason 필드가 포함됩니다. 이러한 값들을 이해하는 것은 다양한 응답 유형을 적절히 처리하는 견고한 애플리케이션을 구축하는 데 중요합니다. API 응답에서 stop_reason에 대한 자세한 내용은 Messages API 참조를 참조하세요.

stop_reason이란 무엇인가요?

stop_reason 필드는 모든 성공적인 Messages API 응답의 일부입니다. 요청 처리 실패를 나타내는 오류와 달리, stop_reason은 Claude가 응답 생성을 성공적으로 완료한 이유를 알려줍니다.

Example response

{
  "id": "msg_01234",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Here's the answer to your question..."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 100,
    "output_tokens": 50
  }
}

중단 이유 값들

end_turn

가장 일반적인 중단 이유입니다. Claude가 응답을 자연스럽게 완료했음을 나타냅니다.

if response.stop_reason == "end_turn":
    # 완전한 응답 처리
    print(response.content[0].text)

max_tokens

Claude가 요청에서 지정한 max_tokens 제한에 도달했기 때문에 중단되었습니다.

# 제한된 토큰으로 요청
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}]
)

if response.stop_reason == "max_tokens":
    # 응답이 잘렸음
    print("Response was cut off at token limit")
    # 계속하기 위해 다른 요청을 고려

stop_sequence

Claude가 사용자 정의 중단 시퀀스 중 하나를 만났습니다.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    stop_sequences=["END", "STOP"],
    messages=[{"role": "user", "content": "Generate text until you say END"}]
)

if response.stop_reason == "stop_sequence":
    print(f"Stopped at sequence: {response.stop_sequence}")

tool_use

Claude가 도구를 호출하고 있으며 실행을 기대합니다.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather?"}]
)

if response.stop_reason == "tool_use":
    # 도구 추출 및 실행
    for content in response.content:
        if content.type == "tool_use":
            result = execute_tool(content.name, content.input)
            # 최종 응답을 위해 Claude에게 결과 반환

pause_turn

Claude가 장시간 실행되는 작업을 일시 중지해야 할 때 웹 검색과 같은 서버 도구와 함께 사용됩니다.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "Search for latest AI news"}]
)

if response.stop_reason == "pause_turn":
    # 대화 계속
    messages = [
        {"role": "user", "content": original_query},
        {"role": "assistant", "content": response.content}
    ]
    continuation = client.messages.create(
        model="claude-sonnet-4-20250514",
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}]
    )

refusal

Claude가 안전상의 우려로 인해 응답 생성을 거부했습니다.

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}]
)

if response.stop_reason == "refusal":
    # Claude가 응답을 거부함
    print("Claude was unable to process this request")
    # 요청을 다시 표현하거나 수정하는 것을 고려