Ketika Anda membuat permintaan ke Messages API, respons Claude menyertakan field stop_reason yang menunjukkan mengapa model berhenti menghasilkan responsnya. Memahami nilai-nilai ini sangat penting untuk membangun aplikasi yang robust yang menangani berbagai jenis respons dengan tepat. Untuk detail tentang stop_reason dalam respons API, lihat referensi Messages API.

​
Apa itu stop_reason?

Field stop_reason adalah bagian dari setiap respons Messages API yang berhasil. Tidak seperti error, yang menunjukkan kegagalan dalam memproses permintaan Anda, stop_reason memberi tahu Anda mengapa Claude berhasil menyelesaikan generasi responsnya.
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
  }
}

​
Nilai stop reason

​
end_turn

Alasan berhenti yang paling umum. Menunjukkan Claude menyelesaikan responsnya secara alami. 
if response.stop_reason == "end_turn":
    # Proses respons yang lengkap
    print(response.content[0].text)

​
Respons kosong dengan end_turn

Terkadang Claude mengembalikan respons kosong (tepat 2-3 token tanpa konten) dengan stop_reason: "end_turn". Ini biasanya terjadi ketika Claude menginterpretasikan bahwa giliran asisten sudah selesai, terutama setelah hasil tool. Penyebab umum:
  • Menambahkan blok teks segera setelah hasil tool (Claude belajar mengharapkan pengguna selalu menyisipkan teks setelah hasil tool, jadi ia mengakhiri gilirannya untuk mengikuti pola)
  • Mengirim respons Claude yang sudah selesai kembali tanpa menambahkan apa pun (Claude sudah memutuskan sudah selesai, jadi akan tetap selesai)
Cara mencegah respons kosong: 
# SALAH: Menambahkan teks segera setelah tool_result
messages = [
    {"role": "user", "content": "Calculate the sum of 1234 and 5678"},
    {"role": "assistant", "content": [
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "calculator",
            "input": {"operation": "add", "a": 1234, "b": 5678}
        }
    ]},
    {"role": "user", "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_123",
            "content": "6912"
        },
        {
            "type": "text",
            "text": "Here's the result"  # Jangan tambahkan teks setelah tool_result
        }
    ]}
]

# BENAR: Kirim hasil tool langsung tanpa teks tambahan
messages = [
    {"role": "user", "content": "Calculate the sum of 1234 and 5678"},
    {"role": "assistant", "content": [
        {
            "type": "tool_use",
            "id": "toolu_123",
            "name": "calculator",
            "input": {"operation": "add", "a": 1234, "b": 5678}
        }
    ]},
    {"role": "user", "content": [
        {
            "type": "tool_result",
            "tool_use_id": "toolu_123",
            "content": "6912"
        }
    ]}  # Hanya tool_result, tanpa teks tambahan
]

# Jika Anda masih mendapat respons kosong setelah memperbaiki hal di atas:
def handle_empty_response(client, messages):
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        messages=messages
    )

    # Periksa apakah respons kosong
    if (response.stop_reason == "end_turn" and
        not response.content:

        # SALAH: Jangan hanya coba lagi dengan respons kosong
        # Ini tidak akan berhasil karena Claude sudah memutuskan sudah selesai

        # BENAR: Tambahkan prompt lanjutan dalam pesan user BARU
        messages.append({"role": "user", "content": "Please continue"})

        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1024,
            messages=messages
        )

    return response
Praktik terbaik:
  1. Jangan pernah menambahkan blok teks segera setelah hasil tool - Ini mengajarkan Claude untuk mengharapkan input pengguna setelah setiap penggunaan tool
  2. Jangan coba lagi respons kosong tanpa modifikasi - Hanya mengirim respons kosong kembali tidak akan membantu
  3. Gunakan prompt lanjutan sebagai pilihan terakhir - Hanya jika perbaikan di atas tidak menyelesaikan masalah

​
max_tokens

Claude berhenti karena mencapai batas max_tokens yang ditentukan dalam permintaan Anda. 
# Permintaan dengan token terbatas
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=10,
    messages=[{"role": "user", "content": "Explain quantum physics"}]
)

if response.stop_reason == "max_tokens":
    # Respons terpotong
    print("Response was cut off at token limit")
    # Pertimbangkan membuat permintaan lain untuk melanjutkan

​
stop_sequence

Claude menemukan salah satu urutan berhenti kustom Anda. 
response = client.messages.create(
    model="claude-sonnet-4-5",
    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 memanggil tool dan mengharapkan Anda untuk menjalankannya. 
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[weather_tool],
    messages=[{"role": "user", "content": "What's the weather?"}]
)

if response.stop_reason == "tool_use":
    # Ekstrak dan jalankan tool
    for content in response.content:
        if content.type == "tool_use":
            result = execute_tool(content.name, content.input)
            # Kembalikan hasil ke Claude untuk respons akhir

​
pause_turn

Digunakan dengan server tools seperti pencarian web ketika Claude perlu menjeda operasi yang berjalan lama. 
response = client.messages.create(
    model="claude-sonnet-4-5",
    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":
    # Lanjutkan percakapan
    messages = [
        {"role": "user", "content": original_query},
        {"role": "assistant", "content": response.content}
    ]
    continuation = client.messages.create(
        model="claude-sonnet-4-5",
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search"}]
    )

​
refusal

Claude menolak menghasilkan respons karena masalah keamanan. 
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "[Unsafe request]"}]
)

if response.stop_reason == "refusal":
    # Claude menolak merespons
    print("Claude was unable to process this request")
    # Pertimbangkan mengubah frasa atau memodifikasi permintaan
Jika Anda sering mengalami alasan berhenti refusal saat menggunakan Claude Sonnet 4.5 atau Opus 4.1, Anda dapat mencoba memperbarui panggilan API Anda untuk menggunakan Sonnet 4 (claude-sonnet-4-20250514), yang memiliki pembatasan penggunaan berbeda. Pelajari lebih lanjut tentang memahami filter keamanan API Sonnet 4.5.
Untuk mempelajari lebih lanjut tentang penolakan yang dipicu oleh filter keamanan API untuk Claude Sonnet 4.5, lihat Memahami Filter Keamanan API Sonnet 4.5.

​
model_context_window_exceeded

Claude berhenti karena mencapai batas jendela konteks model. Ini memungkinkan Anda meminta token maksimum yang mungkin tanpa mengetahui ukuran input yang tepat. 
# Permintaan dengan token maksimum untuk mendapatkan sebanyak mungkin
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=64000,  # Token output maksimum model
    messages=[{"role": "user", "content": "Large input that uses most of context window..."}]
)

if response.stop_reason == "model_context_window_exceeded":
    # Respons mencapai batas jendela konteks sebelum max_tokens
    print("Response reached model's context window limit")
    # Respons masih valid tetapi dibatasi oleh jendela konteks
Alasan berhenti ini tersedia secara default di Sonnet 4.5 dan model yang lebih baru. Untuk model sebelumnya, gunakan header beta model-context-window-exceeded-2025-08-26 untuk mengaktifkan perilaku ini.

​
Praktik terbaik untuk menangani stop reasons

​
1. Selalu periksa stop_reason

Biasakan untuk memeriksa stop_reason dalam logika penanganan respons Anda: 
def handle_response(response):
    if response.stop_reason == "tool_use":
        return handle_tool_use(response)
    elif response.stop_reason == "max_tokens":
        return handle_truncation(response)
    elif response.stop_reason == "model_context_window_exceeded":
        return handle_context_limit(response)
    elif response.stop_reason == "pause_turn":
        return handle_pause(response)
    elif response.stop_reason == "refusal":
        return handle_refusal(response)
    else:
        # Tangani end_turn dan kasus lainnya
        return response.content[0].text

​
2. Tangani respons terpotong dengan baik

Ketika respons terpotong karena batas token atau jendela konteks: 
def handle_truncated_response(response):
    if response.stop_reason in ["max_tokens", "model_context_window_exceeded"]:
        # Opsi 1: Peringatkan pengguna tentang batas spesifik
        if response.stop_reason == "max_tokens":
            message = "[Response truncated due to max_tokens limit]"
        else:
            message = "[Response truncated due to context window limit]"
        return f"{response.content[0].text}\n\n{message}"

        # Opsi 2: Lanjutkan generasi
        messages = [
            {"role": "user", "content": original_prompt},
            {"role": "assistant", "content": response.content[0].text}
        ]
        continuation = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=1024,
            messages=messages + [{"role": "user", "content": "Please continue"}]
        )
        return response.content[0].text + continuation.content[0].text

​
3. Implementasikan logika retry untuk pause_turn

Untuk server tools yang mungkin berhenti sementara: 
def handle_paused_conversation(initial_response, max_retries=3):
    response = initial_response
    messages = [{"role": "user", "content": original_query}]
    
    for attempt in range(max_retries):
        if response.stop_reason != "pause_turn":
            break
            
        messages.append({"role": "assistant", "content": response.content})
        response = client.messages.create(
            model="claude-sonnet-4-5",
            messages=messages,
            tools=original_tools
        )
    
    return response

​
Stop reasons vs. errors

Penting untuk membedakan antara nilai stop_reason dan error sebenarnya:

​
Stop reasons (respons berhasil)

  • Bagian dari body respons
  • Menunjukkan mengapa generasi berhenti secara normal
  • Respons berisi konten yang valid

​
Errors (permintaan gagal)

  • Kode status HTTP 4xx atau 5xx
  • Menunjukkan kegagalan pemrosesan permintaan
  • Respons berisi detail error
try:
    response = client.messages.create(...)
    
    # Tangani respons berhasil dengan stop_reason
    if response.stop_reason == "max_tokens":
        print("Response was truncated")
    
except anthropic.APIError as e:
    # Tangani error sebenarnya
    if e.status_code == 429:
        print("Rate limit exceeded")
    elif e.status_code == 500:
        print("Server error")

​
Pertimbangan streaming

Ketika menggunakan streaming, stop_reason adalah:
  • null dalam event message_start awal
  • Disediakan dalam event message_delta
  • Tidak disediakan dalam event lainnya
with client.messages.stream(...) as stream:
    for event in stream:
        if event.type == "message_delta":
            stop_reason = event.delta.stop_reason
            if stop_reason:
                print(f"Stream ended with: {stop_reason}")

​
Pola umum

​
Menangani alur kerja tool use

def complete_tool_workflow(client, user_query, tools):
    messages = [{"role": "user", "content": user_query}]
    
    while True:
        response = client.messages.create(
            model="claude-sonnet-4-5",
            messages=messages,
            tools=tools
        )
        
        if response.stop_reason == "tool_use":
            # Jalankan tools dan lanjutkan
            tool_results = execute_tools(response.content)
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # Respons akhir
            return response

​
Memastikan respons lengkap

def get_complete_response(client, prompt, max_attempts=3):
    messages = [{"role": "user", "content": prompt}]
    full_response = ""

    for _ in range(max_attempts):
        response = client.messages.create(
            model="claude-sonnet-4-5",
            messages=messages,
            max_tokens=4096
        )

        full_response += response.content[0].text

        if response.stop_reason != "max_tokens":
            break

        # Lanjutkan dari tempat berhenti
        messages = [
            {"role": "user", "content": prompt},
            {"role": "assistant", "content": full_response},
            {"role": "user", "content": "Please continue from where you left off."}
        ]

    return full_response

​
Mendapatkan token maksimum tanpa mengetahui ukuran input

Dengan alasan berhenti model_context_window_exceeded, Anda dapat meminta token maksimum yang mungkin tanpa menghitung ukuran input: 
def get_max_possible_tokens(client, prompt):
    """
    Dapatkan sebanyak mungkin token dalam jendela konteks model
    tanpa perlu menghitung jumlah token input
    """
    response = client.messages.create(
        model="claude-sonnet-4-5",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=64000  # Atur ke token output maksimum model
    )

    if response.stop_reason == "model_context_window_exceeded":
        # Mendapat token maksimum yang mungkin berdasarkan ukuran input
        print(f"Generated {response.usage.output_tokens} tokens (context limit reached)")
    elif response.stop_reason == "max_tokens":
        # Mendapat tepat token yang diminta
        print(f"Generated {response.usage.output_tokens} tokens (max_tokens reached)")
    else:
        # Penyelesaian alami
        print(f"Generated {response.usage.output_tokens} tokens (natural completion)")

    return response.content[0].text
Dengan menangani nilai stop_reason dengan benar, Anda dapat membangun aplikasi yang lebih robust yang menangani skenario respons berbeda dengan baik dan memberikan pengalaman pengguna yang lebih baik.